Close Spec
When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned...
Install
npx skills add dzhng/skills --skill close-spec -g -a claude-code -y- Repository
- dzhng/skills1.4k
- Category
- Writing
- Updated
- 3d ago
- License
- MIT
- Context cost
- Lightabout 1,470 tokens
- Runs scripts
- No, instructions only
What it does
When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale, the why, the principles, the invariants, pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).
Close Spec
A spec is a build plan while you're building and a rationale record once you've shipped. Closing flips it from one to the other. The plan was a ladder of slices and predictions; the record is the layer of meaning the code can't hold, why this exists, what it must never break, what you tried that failed. The code is the single source of truth for how; the closed spec is the source of truth for why, and a map into the code.
Do not summarize the implementation. Anyone can read the code. If a paragraph restates what a function does, cut it and point at the function instead.
Workflow
-
Confirm it shipped. The feature is merged or working in-tree and its tests/screenshot gates are green. If slices remain unverified, it isn't done, finish or review first.
-
Diff plan against reality. Read the spec's README and slices, then read what actually landed. Note every place the build diverged from the plan: dropped slices, renamed seams, a mechanic that turned out different, an assumption that broke. The divergences are the most valuable thing to record, they're exactly what a future reader would otherwise re-derive.
-
Move it.
specs/<feature>/→specs/done/<feature>/(usegit mv). Single-file specs:specs/<feature>.md→specs/done/<feature>.md.
