/how-to-plan

name: how-to-plan
description: Plans self-destruct when shipped (the Inspector Gadget Rule). Use this skill to draft tactical, hand-off-ready planning docs with a 150-word Goal cap, atomic commit steps with verification gates, before/after file trees, and a two-key handshake before deletion. Trigger on "plan this", "write a plan for X", "draft a plan", "make a plan", "plan a refactor", "plan a migration", "plan a deprecation", "design the implementation", "write a PLAN.md", or when scoping multi-commit feature work that needs hand-off. Skip for: subscription plans, query execution plans, quarterly roadmaps, billing plans, sprint plans, test plans (QA matrices).

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.

Only when every branch has a settled answer; scope, domain model, file paths, data shapes, edge cases, out-of-scope items, ordering; begin drafting. Never paper over a gap with `TBD`; a plan with a TBD is a suggestion, not a plan.

Step 2: Split; one plan, one discrete feature

A plan describes a single discrete feature or action. When work grows large enough to contain multiple heavy phases that could each stand alone, split it into multiple plans that reference each other. This is the most important structural choice while drafting.

Goal: keep each plan **as detailed as possible but as bounded as possible**. A plan covering five mixed phases loses detail at every phase to save space overall; two plans, each covering a tighter slice, stay dense where it matters.

Typical split patterns:

| Pattern | First plan | Second plan | |---------|-----------|-------------| | Migration → features | Migrate the data/schema/structure | Build features that assume the new shape | | Infrastructure → consumers | Scaffold the new infrastructure (registry, service, abstraction) | Migrate each consumer onto it | | Deprecation → replacement | Remove the deprecated surface | Build the replacement (or vice versa, per ordering constraint) |

How to split:

1. Look at the projected commit list. If a natural seam exists where the next batch of commits depends on prior commits being **shipped and live** (not just code-complete), that is a split point. 2. The dependent plan starts with a `Depends on:` line in the front matter naming the prior plan and the state it must have reached. Example: *"Depends on: `migrate-resource-schema.md` fully shipped and deployed; `legacy_resources` table dropped."* 3. Each plan self-destructs independently when **its own** work completes.

**Judgment, not a rule.** Three tight phases that share context and edit the same files are fine in one plan. Three heavy phases that touch disjoint file sets, each with its own surface-area inventory, should split. When in doubt, split. A too-small plan is cheap; a too-big plan stays painful the whole time.

Step 3: Decide the plan's scope (scope-aware encapsulation)

A plan's *scope* governs both what its body may reference and where the file lives. A plan checked into a repo is not automatically project-scoped just because the file is there; scope is determined by who will execute it and against what surface. Pick one scope before drafting; declare it as the `Scope:` front-matter value. The five canonical scopes are:

| `Scope:` value | Lives at | Body may reference | |----------------|----------|--------------------| | `model` | `<models-or-db-dir>/<model>/<plan>.md` | The model and its near-neighbors