Write Plan
Overview
A workflow for converting a spec into an executable plan: a numbered list of tasks,
each with a file path, an exact change, a test command, and an acceptance check.
The skill exists because the most common implementation failure is starting from a
plan that says "implement the cache" and discovering at code-review time that
"implement" hid four sub-decisions nobody made. A plan written through this skill
makes those decisions visible up front. Each task is small enough that a different
engineer could pick it up cold; the entire plan is small enough that the spec's
acceptance criteria are obviously reachable from it. Used after shape-spec,
before code or plan-review.
When to Use
- A spec has been approved and you're about to start coding
- The work will span more than one PR or take more than a day
- More than one person will work on the change
- You're handing the work off to a teammate and need them to start without you in
the room
- You ran
plan-review and the reviewer said the plan is too vague to evaluate
When NOT to Use
- The change is Trivial (one-line / single-file / describable in one sentence) — skip planning, make the change, run
verification-gate
- A plan exists; you should be running
plan-review against it, not rewriting it
- You don't have a spec yet and the change is Standard — go to
shape-spec first
Process
Effort tier: planning is for Small and Standard changes. A Small
change (≤ ~3 files, obvious design) needs only a lightweight inline plan — the
task list and per-task acceptance check below, skipping the spec that fed it. A
Standard change gets the full plan and then plan-review. Trivial changes
skip this skill entirely. Either way verification-gate and code-review-loop
still run — planning scales, the gate does not. (Full tier table: README "Sizing
the work".)
Step 1: Confirm the spec is sufficient
Goal: Avoid planning against a spec that itself is incomplete.
Inputs: The spec produced by shape-spec (or equivalent).
Actions:
- Read the spec. Check that Goals, Non-Goals, Constraints, and Acceptance Criteria
sections are all populated.
- For each Acceptance Criterion, write down — in your scratch space, not the plan
— the rough engineering work needed to satisfy it. If you can't, the criterion
is too vague; return to
shape-spec.
- Note any constraint that requires research before tasks can be written
(e.g., "must work with the legacy auth middleware" — does it?). Mark these
as Step 0 tasks.
Output: Confirmation note Spec sufficient or a list of return-to-spec items.
Step 2: Decompose into tasks
Goal: Generate a flat numbered task list. No sub-tasks; flatness forces honesty
about size.
Inputs: The spec's Acceptance Criteria.
Actions:
- For each criterion, list the engineering work needed: data model changes,
handler changes, tests, configuration, documentation, deploy steps.
- Order tasks by data flow: schema/config first, then handlers, then UI, then
tests if not test-first. Reorder if the project uses TDD (test first).
- Each task is on one line in this form:
<N>. <file_path> — <verb> <specific change>. Test: <command>.
- If a task line exceeds ~120 characters or you can't name a single test
command, the task is too large. Split it.
Output: A numbered, flat task list in a Markdown file at
docs/claudekit/plans/<spec-basename>-plan.md.
Step 3: Annotate dependencies and parallelism
Goal: Make the order of operations explicit.
Inputs: The task list from Step 2.
Actions:
- For each task, note tasks that must complete first (dependencies).
- For each task, note tasks that can run in parallel (no shared file, no
shared state).
- Add a
Blocked by: <task numbers> and Parallel with: <task numbers> line
under each task that has either.
- If the dependency graph has a long single chain (everything blocks on task 3),
the work is not parallelizable; tell the reader that explicitly so they don't
try to fan out.
Output: Each task annotated with dependency and parallelism metadata.
Step 4: Add acceptance check per task
Goal: Define what "this task is done" means concretely, so the implementer
knows when to move on and the reviewer knows what to look for.
Inputs: The task list from Step 3.
Actions:
- For each task, append an
Acceptance: line with a concrete observable check.
- For code tasks: a specific test passing OR a specific behavior observable
in the running app.
- For schema tasks: the migration applies cleanly to a snapshot of prod data.
- For docs tasks: the doc renders, the link is valid, the example runs.
- The acceptance check is what the implementer pastes into the PR description
for that task.
Output: Each task has an Acceptance: line.
Step 5: Risk and rollback notes
Goal: Surface the parts of the plan that could go wrong.
Inputs: The fully annotated task list.
Actions:
- Add a
## Risks section at the bottom of the plan. List each task that:
- Touches production data
- Modifies a shared schema
- Changes a public API contract
- Requires a deploy in a specific order with another service
- For each risk, write a one-line rollback procedure.
- If a task has no rollback (e.g., destructive migration), write
Rollback: NOT POSSIBLE — see plan-review-architecture and flag for the
architecture reviewer.
Output: A Risks section. Plan ready for plan-review.
Rationalizations
| Excuse |
Why it sounds reasonable |
Why it's wrong |
What to do instead |
| "I'll figure out the file paths when I get there." |
The plan is for high-level sequencing, not low-level layout. |
Plans without file paths are wishlists. They survive review by saying "implement the X" and rot at implementation time when the engineer realizes "X" actually splits across three files with conflicting conventions. The decisions you defer to "when I get there" are the decisions plan-review exists to catch. |
Name the file path even if it doesn't exist yet. src/handlers/billing/charge.ts (new) is fine. Naming forces you to think about layout before you've written any code. |
| "Test commands will be obvious." |
If the project has one test runner, every task uses it; explicit naming feels redundant. |
"Obvious" assumes the implementer is you, today. A teammate (or you, in three weeks) won't remember whether this task wants pytest -k or the integration suite or the contract test. Naming the exact command in the plan saves the implementer one round trip and avoids the "I ran the wrong tests" PR. |
Paste the exact command. pytest tests/billing/test_charge.py -k test_idempotency. If three tasks have the same command, that's fine; copy-pasting is cheap. |
| "Acceptance is just 'tests pass.'" |
TDD culture tells us tests are the contract. |
"Tests pass" is necessary, not sufficient. A task can pass tests and still not satisfy the acceptance criterion if the test was scoped wrong, the wrong cases were covered, or the criterion includes something tests don't catch (a UX flow, a perf budget, a doc update). The acceptance line names which observable thing proves the task done. |
Write the acceptance line as: "Test X passes AND when I run Y in dev, I see Z." Most tasks need both halves. |
| "I don't need parallelism notes — we'll figure it out as we go." |
Most plans are executed sequentially anyway. Annotating parallelism for a one-person project is overhead. |
The annotation is cheap; the absence is expensive when a second person joins or the same engineer wants to pick the next task while CI runs the previous one. The cases where parallelism notes don't matter are also the cases where adding them takes 60 seconds. |
If the plan has more than 5 tasks, add the parallelism notes. They're not for the first author; they're for whoever is on the project a week from now. |
| "Rollback is the deploy team's problem." |
Some risks really do live in the deploy step, owned by SRE / ops. |
"Their problem" assumes someone else has the context to write the rollback. They don't. The engineer who wrote the migration knows what to undo; SRE can run the rollback but can't author it. The plan owner is the right author of the rollback note. |
Write the one-line rollback yourself. If you don't know what it would be, you don't know what risk you're taking. Flag it; don't punt it. |
| "This change is tiny, but I'll write the full multi-task plan to be safe." |
Thoroughness feels like the safe default, and a plan never hurts. |
A five-task plan for a one-file change is ceremony that trains you and your reviewers to treat the plan as theater — and theater gets skipped next time, including on the Standard change that needed it. Over-applying the process erodes it as surely as skipping it does. |
Size the change (README "Sizing the work"). A Small change gets the lightweight inline plan — the task list and per-task acceptance check, nothing more; a Trivial one skips planning entirely and goes to verification-gate. Save the full plan for Standard work. |
Evidence Requirements
| Checkpoint |
Required artifact |
What "no evidence" looks like |
| End of Step 1 |
A Spec sufficient confirmation OR a list of items to return to the spec |
"I read the spec, I think it's fine." |
| End of Step 2 |
A flat numbered task list with file paths and exact test commands |
"Step 1: implement the feature." |
| End of Step 3 |
Each task annotated with Blocked by / Parallel with (where applicable) |
"We'll figure out the order during implementation." |
| End of Step 4 |
Each task has an Acceptance: line with concrete observable check |
"Tests pass." |
| End of Step 5 |
A ## Risks section with rollback notes for high-risk tasks |
"We'll deal with rollback if it comes up." |
Red Flags
- The plan has fewer than 3 tasks. You wrote a TODO, not a plan.
- The plan has more than 30 tasks. The spec is too big or the tasks are too small;
collapse the trivial ones or split the spec.
- A task has no
Acceptance: line. You don't know how the implementer will know
they're done.
- The dependency graph is one long chain. Either the work isn't parallelizable
(say so) or you missed parallelism opportunities.
- Multiple tasks reference the same file with conflicting changes (one adds,
another modifies, a third removes). Order them, or the second engineer to pick
one will face a merge conflict the plan invented.
- The plan and the spec have drifted. A goal in the spec has no corresponding
task in the plan, or vice versa. Reconcile before review.
References
- Software Engineering at Google, Wright et al. (O'Reilly, 2020), Chapter 9
"Code Review" — the principle "small, focused changes" applied at the planning
level, not just at the PR level. A plan whose tasks are small enough to merge
individually produces PRs small enough to review individually.
1---2name: write-plan3description: Use after a spec exists and before any implementation code is written. Activate for keywords like "plan", "break down", "decompose", "implementation plan", "task list", "what's the order". Produces a numbered task list where each task names the file, the change, the test, and what evidence proves it's done. Always cite file paths and exact commands -- never write a plan with placeholder verbs like "implement" or "set up".4---56# Write Plan78## Overview910A workflow for converting a spec into an executable plan: a numbered list of tasks,11each with a file path, an exact change, a test command, and an acceptance check.12The skill exists because the most common implementation failure is starting from a13plan that says "implement the cache" and discovering at code-review time that14"implement" hid four sub-decisions nobody made. A plan written through this skill15makes those decisions visible up front. Each task is small enough that a different16engineer could pick it up cold; the entire plan is small enough that the spec's17acceptance criteria are obviously reachable from it. Used after `shape-spec`,18before code or `plan-review`.1920## When to Use2122- A spec has been approved and you're about to start coding23- The work will span more than one PR or take more than a day24- More than one person will work on the change25- You're handing the work off to a teammate and need them to start without you in26 the room27- You ran `plan-review` and the reviewer said the plan is too vague to evaluate2829## When NOT to Use3031- The change is **Trivial** (one-line / single-file / describable in one sentence) — skip planning, make the change, run `verification-gate`32- A plan exists; you should be running `plan-review` against it, not rewriting it33- You don't have a spec yet and the change is **Standard** — go to `shape-spec` first3435## Process3637**Effort tier:** planning is for **Small** and **Standard** changes. A **Small**38change (≤ ~3 files, obvious design) needs only a lightweight inline plan — the39task list and per-task acceptance check below, skipping the spec that fed it. A40**Standard** change gets the full plan and then `plan-review`. **Trivial** changes41skip this skill entirely. Either way `verification-gate` and `code-review-loop`42still run — planning scales, the gate does not. (Full tier table: README "Sizing43the work".)4445### Step 1: Confirm the spec is sufficient4647**Goal:** Avoid planning against a spec that itself is incomplete.4849**Inputs:** The spec produced by `shape-spec` (or equivalent).5051**Actions:**52531. Read the spec. Check that Goals, Non-Goals, Constraints, and Acceptance Criteria54 sections are all populated.552. For each Acceptance Criterion, write down — in your scratch space, not the plan56 — the rough engineering work needed to satisfy it. If you can't, the criterion57 is too vague; return to `shape-spec`.583. Note any constraint that requires research before tasks can be written59 (e.g., "must work with the legacy auth middleware" — does it?). Mark these60 as Step 0 tasks.6162**Output:** Confirmation note `Spec sufficient` or a list of return-to-spec items.6364### Step 2: Decompose into tasks6566**Goal:** Generate a flat numbered task list. No sub-tasks; flatness forces honesty67about size.6869**Inputs:** The spec's Acceptance Criteria.7071**Actions:**72731. For each criterion, list the engineering work needed: data model changes,74 handler changes, tests, configuration, documentation, deploy steps.752. Order tasks by data flow: schema/config first, then handlers, then UI, then76 tests if not test-first. Reorder if the project uses TDD (test first).773. Each task is on one line in this form:78 `<N>. <file_path> — <verb> <specific change>. Test: <command>.`794. If a task line exceeds ~120 characters or you can't name a single test80 command, the task is too large. Split it.8182**Output:** A numbered, flat task list in a Markdown file at83`docs/claudekit/plans/<spec-basename>-plan.md`.8485### Step 3: Annotate dependencies and parallelism8687**Goal:** Make the order of operations explicit.8889**Inputs:** The task list from Step 2.9091**Actions:**92931. For each task, note tasks that **must complete first** (dependencies).942. For each task, note tasks that **can run in parallel** (no shared file, no95 shared state).963. Add a `Blocked by: <task numbers>` and `Parallel with: <task numbers>` line97 under each task that has either.984. If the dependency graph has a long single chain (everything blocks on task 3),99 the work is not parallelizable; tell the reader that explicitly so they don't100 try to fan out.101102**Output:** Each task annotated with dependency and parallelism metadata.103104### Step 4: Add acceptance check per task105106**Goal:** Define what "this task is done" means concretely, so the implementer107knows when to move on and the reviewer knows what to look for.108109**Inputs:** The task list from Step 3.110111**Actions:**1121131. For each task, append an `Acceptance:` line with a concrete observable check.114 - For code tasks: a specific test passing OR a specific behavior observable115 in the running app.116 - For schema tasks: the migration applies cleanly to a snapshot of prod data.117 - For docs tasks: the doc renders, the link is valid, the example runs.1182. The acceptance check is what the implementer pastes into the PR description119 for that task.120121**Output:** Each task has an `Acceptance:` line.122123### Step 5: Risk and rollback notes124125**Goal:** Surface the parts of the plan that could go wrong.126127**Inputs:** The fully annotated task list.128129**Actions:**1301311. Add a `## Risks` section at the bottom of the plan. List each task that:132 - Touches production data133 - Modifies a shared schema134 - Changes a public API contract135 - Requires a deploy in a specific order with another service1362. For each risk, write a one-line rollback procedure.1373. If a task has no rollback (e.g., destructive migration), write138 `Rollback: NOT POSSIBLE — see plan-review-architecture` and flag for the139 architecture reviewer.140141**Output:** A Risks section. Plan ready for `plan-review`.142143## Rationalizations144145| Excuse | Why it sounds reasonable | Why it's wrong | What to do instead |146|---|---|---|---|147| "I'll figure out the file paths when I get there." | The plan is for high-level sequencing, not low-level layout. | Plans without file paths are wishlists. They survive review by saying "implement the X" and rot at implementation time when the engineer realizes "X" actually splits across three files with conflicting conventions. The decisions you defer to "when I get there" are the decisions plan-review exists to catch. | Name the file path even if it doesn't exist yet. `src/handlers/billing/charge.ts (new)` is fine. Naming forces you to think about layout before you've written any code. |148| "Test commands will be obvious." | If the project has one test runner, every task uses it; explicit naming feels redundant. | "Obvious" assumes the implementer is you, today. A teammate (or you, in three weeks) won't remember whether this task wants `pytest -k` or the integration suite or the contract test. Naming the exact command in the plan saves the implementer one round trip and avoids the "I ran the wrong tests" PR. | Paste the exact command. `pytest tests/billing/test_charge.py -k test_idempotency`. If three tasks have the same command, that's fine; copy-pasting is cheap. |149| "Acceptance is just 'tests pass.'" | TDD culture tells us tests are the contract. | "Tests pass" is necessary, not sufficient. A task can pass tests and still not satisfy the acceptance criterion if the test was scoped wrong, the wrong cases were covered, or the criterion includes something tests don't catch (a UX flow, a perf budget, a doc update). The acceptance line names *which* observable thing proves the task done. | Write the acceptance line as: "Test X passes AND when I run Y in dev, I see Z." Most tasks need both halves. |150| "I don't need parallelism notes — we'll figure it out as we go." | Most plans are executed sequentially anyway. Annotating parallelism for a one-person project is overhead. | The annotation is cheap; the absence is expensive when a second person joins or the same engineer wants to pick the next task while CI runs the previous one. The cases where parallelism notes don't matter are also the cases where adding them takes 60 seconds. | If the plan has more than 5 tasks, add the parallelism notes. They're not for the first author; they're for whoever is on the project a week from now. |151| "Rollback is the deploy team's problem." | Some risks really do live in the deploy step, owned by SRE / ops. | "Their problem" assumes someone else has the context to write the rollback. They don't. The engineer who wrote the migration knows what to undo; SRE can run the rollback but can't author it. The plan owner is the right author of the rollback note. | Write the one-line rollback yourself. If you don't know what it would be, you don't know what risk you're taking. Flag it; don't punt it. |152| "This change is tiny, but I'll write the full multi-task plan to be safe." | Thoroughness feels like the safe default, and a plan never hurts. | A five-task plan for a one-file change is ceremony that trains you and your reviewers to treat the plan as theater — and theater gets skipped next time, including on the Standard change that needed it. Over-applying the process erodes it as surely as skipping it does. | Size the change (README "Sizing the work"). A **Small** change gets the lightweight inline plan — the task list and per-task acceptance check, nothing more; a **Trivial** one skips planning entirely and goes to `verification-gate`. Save the full plan for Standard work. |153154## Evidence Requirements155156| Checkpoint | Required artifact | What "no evidence" looks like |157|---|---|---|158| End of Step 1 | A `Spec sufficient` confirmation OR a list of items to return to the spec | "I read the spec, I think it's fine." |159| End of Step 2 | A flat numbered task list with file paths and exact test commands | "Step 1: implement the feature." |160| End of Step 3 | Each task annotated with `Blocked by` / `Parallel with` (where applicable) | "We'll figure out the order during implementation." |161| End of Step 4 | Each task has an `Acceptance:` line with concrete observable check | "Tests pass." |162| End of Step 5 | A `## Risks` section with rollback notes for high-risk tasks | "We'll deal with rollback if it comes up." |163164## Red Flags165166- The plan has fewer than 3 tasks. You wrote a TODO, not a plan.167- The plan has more than 30 tasks. The spec is too big or the tasks are too small;168 collapse the trivial ones or split the spec.169- A task has no `Acceptance:` line. You don't know how the implementer will know170 they're done.171- The dependency graph is one long chain. Either the work isn't parallelizable172 (say so) or you missed parallelism opportunities.173- Multiple tasks reference the same file with conflicting changes (one adds,174 another modifies, a third removes). Order them, or the second engineer to pick175 one will face a merge conflict the plan invented.176- The plan and the spec have drifted. A goal in the spec has no corresponding177 task in the plan, or vice versa. Reconcile before review.178179## References180181- *Software Engineering at Google*, Wright et al. (O'Reilly, 2020), Chapter 9182 "Code Review" — the principle "small, focused changes" applied at the planning183 level, not just at the PR level. A plan whose tasks are small enough to merge184 individually produces PRs small enough to review individually.
duthaho