close-spec

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

1. 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.

2. 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.

3. Move it. specs/<feature>/ → specs/done/<feature>/ (use git mv). Single-file specs: specs/<feature>.md → specs/done/<feature>.md.

4. Rewrite the README as a record, not a plan. Keep:

   • Overview & purpose — what shipped and the problem it solves, in present tense ("the economy settles monthly"), not future ("will add").
   • The reason — why it works this way and not the obvious alternatives; the constraints and trade-offs that forced the shape. This is the part the code cannot tell you.
   • Principles & invariants — the rules the implementation must keep honoring. What must stay true; what would silently break if violated.
   • Pointers into the code — greppable module/type/function names, file paths, and the tests that pin the behavior. Send the reader to the code for mechanics; name the entry points so they can find it in one grep.
   • Dead ends — approaches tried and rejected, with the reason, so nobody re-walks them.
   • Visual provenance — any images that were uploaded as a baseline to match, a comparison target, or inspiration for the look. These are the requirement: they say what "done" had to resemble and why the result took the shape it did. Keep them in-tree and reference them from the README, naming where each came from (a real screenshot, a mood board, a reference game) and what it was driving. Without them a reader sees the outcome but not the standard it was held to.