Write a plan
Work out how to build what specs/<slug>/spec.md describes, and write that
next to it as specs/<slug>/plan.md: how the change gets made, and which test
proves each acceptance criterion. The spec stays as it is.
The spec says what and why, and a reviewer reads it. The plan says how, and a
reviewer deliberately does not — so this is the place for approach, trade-offs
and the things you had to decide.
Rules
- No code. Not even a first file. The plan is the artifact; implementation
is a separate stage on the same branch.
- Read before claiming. Every file you name must exist and say what you
think it says. A plan built on a guess costs more than no plan.
- The conventions are in
AGENTS.md — reuse over parallel helpers, the
domain/adapter split, URIs over path strings. The plan is where
you show you've read them; don't restate them here.
- Answer the spec's Open questions, or say plainly which ones need the
maintainer and stop. Don't quietly assume one and build on it.
- The spec is settled. If the work reveals the spec is wrong, say so in the
plan and in your reply — don't silently widen the scope.
Steps
Locate the spec. The active one is specs/<slug>/ where <slug> is
the current branch minus its type prefix. If the branch has no spec, say so
and stop.
Research. Read the files the change will touch, the tests that cover
them, and the nearest existing feature of the same shape.
Settle the open questions. For each one in the spec: answer it with a
file:line citation, or mark it as needing the maintainer. Anything you
assumed goes in the plan under its own heading, so a reviewer can see what
you decided on their behalf.
Write specs/<slug>/plan.md:
# Plan: <title>
## Approach
Two or three paragraphs. What changes, where, and why this way rather than
the obvious alternative.
## Work breakdown
1. ...
2. ...
## AC verification map
- AC-1 → `packages/foam-core/src/templates/variable-resolver.test.ts`
- AC-8 → `packages/foam-vscode/src/vscode/features/notes/create-note.spec.ts`
## Decisions
- <question from the spec> → <answer>, per `path/to/file.ts:42`
## Risks
- What could break elsewhere, and what would catch it.
Check the map covers the wiring, not just the logic. A feature reached
through more than one path (core and the VS Code adapter, say) can pass
every unit test while one path was never hooked up. If no criterion covers
that, say so in Risks and name the test that should.
Commit specs/<slug>/plan.md to the current branch:
git commit -m "Add plan for <title>".
Hand it back. Running in CI, push to the PR branch and comment on the
thread — the plan is only useful if it gets read before the code exists.
The comment carries the approach in a few sentences, the decisions you made
on the maintainer's behalf, anything you need them to settle, and this
block verbatim:
Next: comment @claude implement to build it, or reply here with
changes to the plan first.
Locally, stop after the commit and say the branch is ready to push —
AGENTS.md is clear that nothing leaves the machine unasked.
1---2name: write-plan3description: Work out how to build what a spec describes, and write it to plan.md. Use when asked to plan a spec, or when an @claude comment on a spec PR asks for the plan.4allowed-tools: Bash(gh:*), Bash(git:*), Bash(yarn:*), Read, Write, Edit, Glob, Grep5metadata:6 source: https://skillmd.com/skills/tuyv/write-plan7---89# Write a plan1011Work out how to build what `specs/<slug>/spec.md` describes, and write that12next to it as `specs/<slug>/plan.md`: how the change gets made, and which test13proves each acceptance criterion. The spec stays as it is.1415The spec says what and why, and a reviewer reads it. The plan says how, and a16reviewer deliberately does not — so this is the place for approach, trade-offs17and the things you had to decide.1819## Rules2021- **No code.** Not even a first file. The plan is the artifact; implementation22 is a separate stage on the same branch.23- **Read before claiming.** Every file you name must exist and say what you24 think it says. A plan built on a guess costs more than no plan.25- **The conventions are in `AGENTS.md`** — reuse over parallel helpers, the26 domain/adapter split, URIs over path strings. The plan is where27 you show you've read them; don't restate them here.28- **Answer the spec's Open questions**, or say plainly which ones need the29 maintainer and stop. Don't quietly assume one and build on it.30- The spec is settled. If the work reveals the spec is wrong, say so in the31 plan and in your reply — don't silently widen the scope.3233## Steps34351. **Locate the spec.** The active one is `specs/<slug>/` where `<slug>` is36 the current branch minus its type prefix. If the branch has no spec, say so37 and stop.38392. **Research.** Read the files the change will touch, the tests that cover40 them, and the nearest existing feature of the same shape.41423. **Settle the open questions.** For each one in the spec: answer it with a43 `file:line` citation, or mark it as needing the maintainer. Anything you44 assumed goes in the plan under its own heading, so a reviewer can see what45 you decided on their behalf.46474. **Write `specs/<slug>/plan.md`:**4849 ```markdown50 # Plan: <title>5152 ## Approach5354 Two or three paragraphs. What changes, where, and why this way rather than55 the obvious alternative.5657 ## Work breakdown5859 1. ...60 2. ...6162 ## AC verification map6364 - AC-1 → `packages/foam-core/src/templates/variable-resolver.test.ts`65 - AC-8 → `packages/foam-vscode/src/vscode/features/notes/create-note.spec.ts`6667 ## Decisions6869 - <question from the spec> → <answer>, per `path/to/file.ts:42`7071 ## Risks7273 - What could break elsewhere, and what would catch it.74 ```75765. **Check the map covers the wiring, not just the logic.** A feature reached77 through more than one path (core and the VS Code adapter, say) can pass78 every unit test while one path was never hooked up. If no criterion covers79 that, say so in Risks and name the test that should.80816. **Commit** `specs/<slug>/plan.md` to the current branch:82 `git commit -m "Add plan for <title>"`.83847. **Hand it back.** Running in CI, push to the PR branch and comment on the85 thread — the plan is only useful if it gets read before the code exists.86 The comment carries the approach in a few sentences, the decisions you made87 on the maintainer's behalf, anything you need them to settle, and this88 block verbatim:8990 > **Next:** comment `@claude implement` to build it, or reply here with91 > changes to the plan first.9293 Locally, stop after the commit and say the branch is ready to push —94 `AGENTS.md` is clear that nothing leaves the machine unasked.