Codex Task Decomposition skill for Codex

Decomposition is right when every step leaves the repository green, is small enough to review in a few minutes, has a check that proves it, and could be handed to a fresh session using only the plan file. Big-bang diffs that are “almost done” are the failure this prevents.

Signals that a task needs splitting

• Touches more than about 10 files or more than one module boundary.
• Mixes a refactor with a behavior change.
• Needs a schema, API or dependency change that consumers must follow.
• Cannot state a single check command that proves the whole thing.
• A previous attempt ran out of context, compacted repeatedly, or produced a diff you could not review.

Slicing strategies

Situation	Slice by	Each step ends with
New feature across layers	Vertical slices: one thin end-to-end path at a time	Feature flag off by default; a test for the slice
Renames, API changes with many callers	Expand, migrate callers in batches, contract	Old and new APIs both work until the last step
Replacing a subsystem	Strangler: route one use case at a time to the new code	Characterization tests pass on both paths
Language or framework migration	File or module batches in dependency order (leaves first)	Typecheck + tests green per batch
Risky legacy change	Characterization tests first, then change	Tests that pin current behavior
Investigation plus fix	Separate read-only investigation step, then fix steps	Written root cause before any edit

Rule: refactor steps and behavior-change steps never share a commit.

Workflow

- [ ] 1. Investigate read-only and draft the plan (/plan)
- [ ] 2. Write the plan file with steps, checks and stop conditions
- [ ] 3. Execute one step at a time; verify; commit
- [ ] 4. Parallelize only independent steps (subagents, worktrees)
- [ ] 5. Re-plan when reality diverges; finish with the full check

1. Investigate and draft

Start in plan mode so nothing is edited while the shape is unclear:

/plan Migrate order totals from float dollars to integer cents across services/orders
and apps/web. Map every read and write of `total`, list the consumers, and propose
steps that each keep the build green. Do not edit files.

Read the plan critically: are steps ordered by dependency? Does each have a check? Is any step secretly two steps?

2. Plan file

Commit the plan so any session (or person) can continue from it:

# Plan: order totals in integer cents
Owner: @dana  Branch: feat/cents  Started: 2026-10-28
Global check: `pnpm turbo run typecheck test --filter=...[origin/main]`

## Steps
- [x] 1. Add `totalCents` column + backfill migration (no reads yet)
      Check: `pnpm --filter orders test migrations`  Commit: a1b2c3d
- [ ] 2. Write both fields in OrderService.save; read old field
      Check: `pnpm --filter orders test`
- [ ] 3. Switch readers in services/orders to totalCents (batch: api/, jobs/)
      Check: same + contract tests
- [ ] 4. Switch apps/web formatting to cents
      Check: `pnpm --filter web test`; screenshot of invoice page
- [ ] 5. Stop writing `total`; drop column in a follow-up release
      Check: global check; grep -rn "\.total\b" returns nothing in src

## Stop and ask if
- A consumer outside this repo reads `total`.
- Any step needs more than ~15 files.

## Decisions
- Rounding: banker's rounding during backfill (see #482).

Put it at docs/plans/<topic>.md or wherever AGENTS.md says plans live.

3. Execute step by step

Prompt per step, referencing the plan rather than restating it:

Do step 2 of docs/plans/order-cents.md only. Run its check. If it passes, tick the box,
add the commit hash after I commit, and stop. If it fails twice, stop and explain.

• Commit after each green step (or ask the user to); the commit is the rollback point.
• Run /review or codex review --uncommitted on the step’s diff before committing.
• For a long run with a clear end state, /goal can drive the steps: /goal Complete docs/plans/order-cents.md steps 2-4; each step's check must pass; stop at "Stop and ask" conditions. A goal keeps the same sandbox and approval policy.
• When context gets heavy, /compact, or start a new session pointed at the plan file; the plan, not the chat history, is the source of truth.

4. Parallelize safely

Work type	Mechanism
Independent read-heavy exploration (map callers, read logs, check docs)	Ask Codex to use subagents; each returns a summary to the main thread
Independent write steps touching disjoint files	Separate sessions in separate git worktrees (/worktree, codex exec --worktree "...")
Long implementation that can run unattended	Codex Cloud task from a published environment
Steps that depend on each other	Sequential only

Never let two sessions write the same files. Subagents cost extra tokens; use them when the parallel parts are genuinely independent.

5. Re-plan

When a step reveals something the plan missed, stop, update the plan file (new step, changed order, a decision recorded), and continue. Finish with the global check and a final diff review across all steps.

Gotchas

• “Small steps” that leave the build red between them are not steps; every commit must pass its check, or the rollback point is useless.
• Plans written without the read-only investigation invent file paths. Verify paths exist.
• Codex will happily do steps 2 to 5 in one go if the prompt allows it. Say “only step N, then stop”.
• Generated files and lockfiles create merge conflicts between parallel worktrees; serialize steps that regenerate them.
• Database migrations and public API removals deserve their own steps and explicit user confirmation before running against shared environments.

Output contract

**Plan:** docs/plans/order-cents.md (5 steps, global check defined)
**Progress:** steps 1-3 done (commits a1b2c3d, d4e5f6a, 0718bcd), all checks green
**Next:** step 4 (apps/web formatting); blocked on: none
**Changes to plan:** added step 3b for the reporting job found during step 3