toppa/write-plan_SKILL.md

## write-plan_SKILL.md

      
    Raw
  

              write-plan_SKILL.md
            
          
    name
    write-plan
  
  
    description
    How a plan document is written — where the file lives, what it is called, what it carries, and the approval it needs before implementation starts.
  
  
    when_to_use
    Use when you write a plan document, when you update one, and in plan mode. Also use it when the user asks for a plan, asks for a design to be written down, or asks where a plan file belongs. For the workflow that runs while the plan is implemented, use the `dev-workflow:implement-plan` skill.
  
  
Writing a plan

Standing documents outrank the plan

A plan is temporary. It ends when the work ships. A standing document outlives it.
A project's CLAUDE.md names its standing documents. A glossary, a rules file, and a set
of ADRs are all of that kind, and so are CLAUDE.md and README.md themselves. Where one
exists, the plan defers to it.

Read it first. Write the plan against the terms and the rules those documents
already hold.
State a rule once. Where the plan needs a rule a standing document holds, give it in
one line and name the document that holds it. Leave the reason where it is. Two copies
of one reason drift.

An epic that governs several plans outranks each of them the same way. It lives in the
plan directory, and it ends when its work ships.
The implement-plan skill's "Step completion workflow" covers the other direction: a step
that settles a term or a rule edits the standing document in that same step.
A document CLAUDE.md does not name is not standing. A brainstorm, a scratch design, or a
spec from an earlier session is input. Fold its decisions into the plan. Leave the
document as it is.
Where the file lives, and what it is called

The plan directory is docs/plans/, unless the project's CLAUDE.md names
another one. Write the plan there.
Name the file with a YYYYMMDD date, a hyphen, and a verb phrase:

20251219-improve-show-selection-catalog.md
20251220-display-multiple-provider-logos.md

Use that name even when the system suggests one of its own. A suggested name is random
— greedy-mixing-jellyfish.md — and carries neither the date nor the verb phrase.
In plan mode

Plan mode names its own plan file, and ExitPlanMode reads the plan from that file. So a
plan written in plan mode starts life under the system's name. Write it there. Move the
file to the plan directory under the name above once the user approves it. Do that before
you stop, and move the file rather than copy it, so one plan file remains.
File structure


Title — an H1 that says what the plan does.
Status — a line under the Title: **Status:** not started. The value is one of
not started, in progress, or done. A new plan carries not started. The
implement-plan skill writes the other two.
Context — an opening that states the why: the goal, and where you weighed
alternatives, the reason for this approach. Every plan carries one, because a plan that
does not say why it exists is a worse plan. Scale it to the decisions rather than to a
fixed length: one sentence for a small standalone change, and as much as it takes to
keep the reasoning where the design involved real tradeoffs.
Steps that tell a story, each building on the one before it.

Each step is small, and focused on one logical and cohesive change. It may span
several files.
Tests for new or changed behavior belong in the step that changes the behavior, not in
a later step. Skip them where they do not apply, as for a Rake task, a script, or
trivial config.
A finished step is marked ✅.


To draw the boundary between one step and the next, use the organize-commits skill. Its
"Separate semantic changes from structural refactors" and "Walk through bundled changes
before making them" sections apply to a step as they do to a commit.
Approval, then stop

Ask the user to review and approve the plan. Then stop and wait, even after they approve
it. Implementation starts on its own instruction, under the implement-plan skill.
name	write-plan
description	How a plan document is written — where the file lives, what it is called, what it carries, and the approval it needs before implementation starts.
when_to_use	Use when you write a plan document, when you update one, and in plan mode. Also use it when the user asks for a plan, asks for a design to be written down, or asks where a plan file belongs. For the workflow that runs while the plan is implemented, use the `dev-workflow:implement-plan` skill.
No results found