how-to-plan

How to Plan

A plan is the contract between the session that designs the work and the session that executes it. It only works if it is explicit enough to hand off cold to a fresh agent or a junior engineer who has none of your conversation context.

This skill encodes the methodology for producing such plans. Follow it in order.

Workflow at a glance

1. Interview the developer using the interrogation protocol below. No prose until every branch of the decision tree has a settled answer.
2. Split. One plan, one discrete feature. Split early if multiple heavy phases would otherwise share a doc.
3. Decide the plan's scope (model / subsystem / cross-stack / project-meta / cross-repo). Scope governs both what the body may reference and where the file lives.
4. Name the file descriptively. Never PLAN.md.
5. Draft the plan with required front matter, required sections, ASCII file trees, and atomic commit steps with verification gates.
6. Execute against the plan; mark progress with status glyphs.
7. Self-destruct the plan via the two-key Inspector Gadget Rule when work is verifiably done.

Each step is detailed below. References in references/ carry the long-form templates and anti-patterns.

Step 1: Interrogate before drafting

No code is authored until the plan is airtight. An airtight plan is one a weaker model could execute to a correct outcome without asking a follow-up question. Write for the dumbest plausible executor, not for the author.

Reaching that bar requires interrogation. Before drafting any plan prose, interview the developer about every branch of the design tree until shared understanding is reached.

The interrogation protocol

1. Ask one question at a time. Never batch. The answer to Q1 reshapes Q2; asking both at once wastes the answer to the first.
2. For each question, propose the recommended answer. Not "what should we do about X?"; "I would do X because Y; does that match your intent?" Confirmation, correction, and elaboration are all higher-signal than a blank prompt.
3. Walk the decision tree branch by branch. Resolve upstream choices before moving laterally. If a downstream choice depends on an upstream decision, settle the upstream one first.
4. Explore the codebase instead of asking whenever a question can be answered by reading files. Burning the developer's time on facts you can look up is rude and slow.
5. Do not stop early. Drafting with unresolved questions guarantees the executor will hit them mid-flight and either guess (wrong) or stall (slow). Neither is acceptable.