Plan a Code Change

A good plan makes the implementation obvious: whoever executes it (you later, a subagent, a teammate) never has to guess a file, a name, a value or how to prove a step worked. You plan in read-only mode, you find every place the change touches before you commit to an approach, and you de-risk the scariest unknown first.

When to use

• "Plan this out before you start", "how would you build X?", "how big is this?", "write an ADR for Y".
• The change touches more than a couple of files, a public interface, a database schema or another team's code.
• You intend to hand parts of the work to subagents or teammates.
• The owner must choose between approaches.

What you need

• The request in the owner's words, plus any issue, spec, design or screenshot. Read attachments fully (read_file, vision_analyze for images).
• A map of the repo. If you have not worked in it, build one first (commands, layout, conventions, baseline test result).
• Read access to the repository (GitHub or GitLab connected app, or a local checkout). Planning needs no write access.

Method

1. Stay read-only. While planning, edit nothing except the plan file. No commits, no installs that change lockfiles, no migrations.

2. Restate the goal and the acceptance criteria. One sentence of goal, then criteria as checkable statements ("Given a cart with an expired coupon, when the user checks out, then the total excludes the discount and the response says why"). Write what is out of scope. If an ambiguity would change the design, ask the owner with clarify, offering two or three concrete options and your recommendation. If it would not, state your assumption and move on.

3. Find the blast radius. For every function, type, endpoint, table, config key, event or CLI flag you expect to touch:

   • search_files for the exact name with word boundaries (\bplace_order\b), then for string forms ("place_order", 'place-order') in code, templates, YAML, SQL, docs and tests.
   • List each caller as file:line. Check other packages in a monorepo and, if this is a library or API, its known consumers.
   • Note the tests that cover the area and how to run them.
   • Note data effects: schema changes, backfills, cache keys, queued jobs that will meet the new code mid-flight.

4. Size it.

   Size	Signals	Planning depth
   Small	1 to 2 files, no interface change, under about 50 changed lines	A short task list is enough
   Medium	several files, or one internal interface change	Full task list with tests per task
   Large	public API or schema change, cross-service, data migration, or over about 400 changed lines	Split into independently shippable steps; consider a feature flag; get owner sign-off
   For large changes, plan an expand and contract sequence: add the new path alongside the old, move callers over, then remove the old path in a later step. Each step ships on its own and can be rolled back alone.

5. Kill the scariest unknown first. Name the assumption that would sink the plan if wrong ("the payment SDK supports partial refunds", "this query stays under 100 ms at production size"). If reading docs or code can settle it, settle it now (web_extract the docs, read the source). If only running code can, plan a time-boxed throwaway spike as task 1 and make the rest conditional on its result.

6. Choose the approach. If there is one obvious approach that matches existing patterns, use it and say why. If two or three are viable, compare them in a short table (effort, risk, reversibility, fit with existing code, operating cost) and recommend one. When the choice will outlive this change (a new dependency, datastore, protocol, framework, or a public contract), write a decision record using references/decision-record.md and get the owner or the CTO to accept it before building.

7. Write the tasks. Each task is one logical change that leaves the build green and could be reviewed alone. Use vertical slices (one behaviour through all layers) rather than horizontal ones (all models, then all endpoints). Every task states:

   • files to create or modify, with exact paths (and line ranges when known);
   • the interface it produces or consumes (exact names, parameters, return types);
   • the test to write first and what it asserts, with the spec's exact values;
   • the command that proves it, and the expected result ("pytest tests/test_coupons.py -k expired -q passes, 3 tests");
   • the commit message. Order tasks so risky and foundational ones come first. A task that says "handle edge cases" or "add validation" decides nothing: name the cases.

8. Mark what can run in parallel. Tasks that share no files and no interfaces can go to separate subagents with delegate_task. Tasks that touch the same file never run in parallel. Write the dependencies down ("task 4 needs task 2's CouponPolicy").

9. Plan the way back. For each risky step: how you would notice it failing (test, metric, log line) and how to undo it (revert the commit, turn off the flag, run the down migration, restore from the snapshot taken in step N). If a step cannot be undone (data deletion, a public release), mark it and require the owner's go-ahead.

10. Review the plan against the request. Walk the acceptance criteria one by one and point to the task that satisfies each. Check names and types are consistent across tasks. Check the plan is shorter than the code it describes: if it is mostly code bodies, replace them with signatures and test assertions.

11. Save and share. Write the plan with write_file to the place the project keeps plans, or plans/<YYYY-MM-DD>-<slug>.md in your workspace (do not commit it unless the project keeps plans in the repo). Mirror the tasks into todo when you start executing. For medium and large plans, put the summary on a show_card for the owner: goal, approach, number of tasks, risks, decisions needed.

Output

A plan in the shape of references/plan-template.md, plus a short message: the goal in one line, the chosen approach in one or two lines, the task count, the top risks, and any decision you need from the owner. For a decision record, use references/decision-record.md and state the recommended option first. For example:

Plan saved: plans/2026-10-05-expired-coupons.md
Goal: reject expired coupons at checkout and tell the shopper why.
Approach: a CouponPolicy check in the existing discount pipeline; no schema change.
Size: medium, 5 tasks (blast radius: 3 callers of apply_coupon, 1 email template).
Risks: mobile app v3 sends coupons in a different field; kept compatible in task 2.
Decision needed: should expired coupons fail the order or just drop the discount? I recommend dropping the discount with a message.

Checks before you finish

• Every acceptance criterion maps to at least one task.
• Every task has exact paths, a test, a verification command and an expected result.
• Every caller of every changed interface is listed and covered by a task.
• Irreversible steps are marked and gated on the owner.
• Nothing in the repo was modified except the plan file.

Pitfalls

• Planning from the request instead of the code. You find the third caller after you have shipped. Search first, then plan.
• Vague tasks. "Update the API" cannot be checked. "Add expires_at to CouponOut in api/schemas.py and assert it in test_coupons.py::test_get_coupon" can.
• Horizontal slicing. Building every layer before any behaviour works hides integration problems until the end.
• Gold-plating. Plan what was asked. Flexibility for imagined futures is cost now and maybe never value.
• Skipping the spike. Two days of plan built on an untested assumption is two days lost.
• Hiding the decision. If the owner has to choose (cost, vendor, trade-off), ask; do not bury the choice in task 7.
• Plans nobody can run. No verification commands means "done" will be a guess.