plan

Planning a change

A plan written without reading the code is a guess with headings. Before proposing anything, spend the cheap calls that tell you what you are planning into. All of these run on the CPU and cost nothing to produce:

node ${CLAUDE_PLUGIN_ROOT}/hooks/recall.mjs map            # what exists
node ${CLAUDE_PLUGIN_ROOT}/hooks/recall.mjs duplicates     # what is already repeated
node ${CLAUDE_PLUGIN_ROOT}/hooks/recall.mjs decide --list  # what was already settled
node ${CLAUDE_PLUGIN_ROOT}/hooks/recall.mjs search <topic> # what was tried before

The last two matter most. Proposing something the team already rejected, for reasons recorded months ago, is the most common way a plan wastes everyone's time — and the reason is usually still valid.

Shape of a good plan

Phases, each one shippable. A phase that cannot be merged on its own is not a phase, it is a step in a phase. If the branch must contain all five to work, the plan has one phase and you should say so rather than pretend otherwise.

Every phase names its check. Not "test it" — the specific thing that fails if the phase is wrong: a test file, a command with expected output, a page that should render. A phase without a check is a phase nobody can verify you finished.

Order by risk, not by comfort. The step most likely to invalidate the plan goes first, while changing course is still cheap. Doing the easy renames first feels productive and buys nothing.

Name what you are not doing. Every plan has a boundary; leaving it implicit is how scope grows silently. Write the excluded items down.

Sizing

Estimate in files touched and whether the change is reversible, never in hours. "Three files, additive, revert is a git revert" tells the reader everything they need; "about two days" tells them nothing they can check.

Flag anything irreversible explicitly: schema migrations that drop columns, data backfills, published API changes, anything with a deploy that cannot be rolled back. Those deserve their own phase and their own rollback note.