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.

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 | //.md | The model and its near-neighbors only. Don't reach across the data layer. | | subsystem (one folder, one concern; includes monorepo packages) | /.md | Real symbol names, domain nouns, internal helpers, real file paths. Anchor to the codebase: that's the value. | | cross-stack | Repo root | Project-internal identifiers freely. Default for anything spanning frontend + backend, or large enough to need persistent state across multiple agent sessions. | | project-meta | Repo root or docs/process/ | Repo-level configs, workflow files, CI/release tooling, durable convention docs. Avoid feature-domain nouns: the plan affects all features but is owned by none. | | cross-repo | Template repo or shared docs | Generic placeholder names; abstract patterns; no codebase-specific helpers. Same depth gate as a global skill. |

Rule of thumb: bigger than a breadbox and needs a planning doc to persist state across multiple agent sessions → cross-stack at repo root, unless it cleanly belongs to one folder (subsystem) or one model (model). A monorepo package counts as a subsystem; a plan touching one package lives inside that package; a plan touching many is cross-stack at the monorepo root.

Verification: before the draft is "ready," grep the body against the declared scope. cross-repo plan with project-specific paths → genericize. subsystem plan reading like a template → specialize. project-meta plan that names a feature's symbols → either move into a subsystem plan or abstract the noun. Mismatch = draft, not plan.

Step 4: Name the plan file

Never name a plan file PLAN.md. Generic names do not survive; six months later no one can tell what the plan was about without opening it, and greps for feature names miss it.

The filename must describe what the plan does. Use kebab-case, imperative-ish phrasing.

| Good | Bad | |------|-----| | deprecate-legacy-mocks.md | PLAN.md | | refactor-field-resolvers-pattern.md | plan.md | | migrate-image-uploads-to-s3-presign.md | notes.md | | onboarding-experience-flow.md | refactor.md |

File placement follows the Scope: chosen in Step 3; see the scope-table column "Lives at."

Step 5: Draft the plan

Every plan needs the same front matter and the same ordered sections.

Required front matter

# 

**Status:** Draft | In progress | Descoped | Archived
**Scope:** model | subsystem | cross-stack | project-meta | cross-repo
**Date:** YYYY-MM-DD              
**Last reviewed:** YYYY-MM-DD     
**Context:** 
**Depends on:** `.md` …    

The Status enum is closed; do not invent modifiers (Draft; blocked on X). If a plan is blocked, keep Status: Draft and put the blocker in the Context: line.

The Scope: field is set in Step 3 and governs what the body may reference.

Update Last reviewed on every non-trivial edit; a stale plan is a trap. If you read a plan without editing it and it still looks correct, bump Last reviewed anyway with a one-line # verified still accurate note in the front matter; that signal protects future readers from second-guessing.

Depends on: is included only when the plan needs another plan shipped and live before this one starts. Name the prior plan and the state it must have reached: "Depends on: migrate-resource-schema.md fully shipped and deployed; legacy_resources table dropped."

Required sections, in order

1. Goal: north star. One short paragraph. See "The Goal section" below; most load-bearing part of the document.
2. Domain context: 3–5 concepts the reader must hold in their head, defined even if "obvious."
3. Current surface area: inventory of every file, table, route, component, or export the plan touches. Use tables; cite paths; count lines where size matters.
4. File structure: before: ASCII tree of starting state for every directory the plan touches. Required only when the plan creates, moves, renames, splits, or deletes files; omit if the plan only changes schema rows, process docs, or in-place content with no structural shift.
5. File structure: after: ASCII tree of end state. Annotate each transformed node with the legend symbol; place a **Legend:** line directly above the tree, trimmed to operation symbols actually used; carry lineage in // from … notes. Canonical legend, mutex table, and combinable annotations live in references/file-tree-annotations.md: load it once and treat it as authoritative; the symbol set is not duplicated here to prevent drift. Same omission rule as the before-tree.
6. Commits: ordered, atomic execution steps. See "Step quality" below.
7. Verification checklist: final gate; every box must check before "done."
8. References: file paths to related plans, project docs, external URLs.

Situational sections (include when relevant):

• Data flow diagram when the plan changes how data moves.
• Domain categories when the plan disambiguates concepts.
• Target state per item when many items each migrate to a different shape (before→after table per row).
• Open questions + Answered questions (track decisions explicitly).
• Interrogation log for plans shaped across multiple design sessions.
• Anti-patterns / scope boundaries: what is explicitly NOT in scope.

The Goal section: north star, not a summary

This is the single most important paragraph in the document; more than file trees, more than the commit list. Everything downstream derives meaning from the Goal.

The Goal must answer three questions, in order:

1. Why does this plan exist? What problem or opportunity triggered writing it. Not "we want to refactor X"; why we want to refactor X, what is wrong today, what is blocked, what is rotting.
2. What are we doing about it? One sentence naming the intervention. Not the mechanics; just the shape: "move X into Y," "deprecate X in favor of Y," "introduce a Y to replace the implicit X."
3. What does done look like? A one-paragraph description of the desired end state, concrete enough that a cold reader can recognize whether the current code matches.

Cap the Goal at ~150 words. A Goal that runs longer is doing someone else's job.

The Goal is the reference point both author and executor consult to answer two recurring questions:

• "Are we still on scope?"; Every commit, every file change, every suggested tangent gets measured against the Goal. If a proposed change does not advance the Goal, it does not belong in this plan. (It might still be a good idea; split it into a different plan.) Scope creep happens when the Goal is soft.
• "Are we done? Should this plan self-destruct?"; Read the Goal, compare it against current file state and commit history. If the desired end state already matches reality, the plan is done (or was never needed). If the gap is narrowing but not closed, the plan is mid-flight. This only works if the Goal is concrete enough to check against the code.

File structure diagrams

Non-negotiable when the plan creates, moves, renames, or deletes files. The before/after trees are the single most important transformation aid for the executing session; they let the executor reason about "this turns into that" without juggling prose.

Step quality

Each step states:

• What happens: create file, delete file, move file, rewrite file, update import, regenerate artifact. No abstract verbs ("refactor the thing").
• Which files: exact paths, not "the relevant files."
• What the file contains: for new files: exports, types, key patterns. For rewritten files: before/after sketch or enough signal that the executor can reproduce the change.
• Gate: the verification that must pass before the next step begins. Usually the project's full validation command. May also include: a specific test subset, a Storybook story renders, a grep returns zero matches, etc.

Step template (use only the file-action subsections that apply; omit empty ones):

### Commit N: 

**Goal:** 

**Files created:**
- `path/to/new-file.ts`: 

**Files rewritten:**
- `path/to/existing.tsx`: 

**Files moved/renamed:**
- `path/to/new.ts ← path/to/old.ts`: 

**Files deleted:**
- `path/to/deadcode.ts`

**Gate:**  passes. 

The Files moved/renamed: subsection mirrors the 🔀 new ← old notation from references/file-tree-annotations.md, so the commit text and the file tree describe the same operation in the same shape.

No Files split: subsection; splits decompose into existing subsections. The split source goes under Files rewritten: (if it survives the split) or Files deleted: (if it goes away); the targets go under Files created: with // from 🪓 notes. The 🪓 symbol carries the split semantics in the file tree; the commit text uses the regular subsections. This is the same trade-off merge makes (no symbol; lineage via // from a + b).

Sub-letter commits (3a / 3b / 3c)

When several commits share the same shape; same file-action subsections, same Gate, same template; and differ only by a single swap (which mutation, which model, which consumer), number them with sub-letters tied to one parent number:

### Commit 3a: 
…full step body…

### Commits 3b, 3c, 3d:  (same shape)

Each follows Commit 3a's template verbatim with the  name swapped. Three separate commits, each with its own Gate; do not collapse into one.

Use sparingly: only when the commits are genuinely identical except for the swap. The first sub-letter (3a) is shown concretely with all subsections and a Gate; the rest get a one-line note. This keeps the parent number tied to the conceptual unit ("the per-action migration") instead of spraying eight sequential numbers across what is one step's worth of intent.

Between major sections (phase boundary, grouped commits), the gate is all checks pass: the project's full validation command at minimum; add scoped tests, Storybook smoke, or a grep assertion when the change touches those layers.

Status glyphs (track-progress markers)

Use these to mark progress through the plan's commits or sections in long-running plans; not to mark file-operation outcomes (the file-tree legend covers that):

| Marker | Meaning | |--------|---------| | ✅ | Complete | | 🔶 | Partial / In progress | | ❌ | Not started | | 🚫 | Descoped / will not do |

Hard rule; no cross-pollination between systems:

• File-op symbols (the legend in references/file-tree-annotations.md) never appear in commit checklists, status tables, or anywhere outside file trees.
• Progress glyphs (🔶 ✅) never appear inside file-tree nodes. *(🔶 and ✅ exist in the file-tree legend only for the long-runnin

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: simiancraft
• Source: simiancraft/simiancraft-skills
• License: MIT

Install and usage instructions live in the source repository linked above.