speccing

Speccing

Some repositories keep their product intent in files: a living spec per area, a versioned roadmap, an append-only decision log, and a backlog of wishes. Those files are the product's memory. This skill is how you work without corrupting it.

The law

THE SPEC AND THE CODE MERGE IN THE SAME PR
A RECORDED DECISION IS NEVER EDITED

A spec that lags the code is worse than no spec: the next reader trusts it and builds on a promise the code stopped keeping. A decision log you edit records what you currently believe rather than what you chose and why — which is the one thing it existed to preserve.

When this does not apply

• The repo keeps no product state and the user did not ask for any. Do not create it because it would be tidy — see step 1.
• The design is still open. Settle what to build with /brainstorming; this skill records what was settled.
• The change has no product footprint: a typo, a refactor with identical behavior, a dependency bump.

1. Bootstrap only when asked

Starting the ledger is a commitment the user makes. Offer once when the fit is obvious, then wait for a yes.

Once asked, four files: product/ROADMAP.md (the version table and the decision log), product/BACKLOG.md (the wishes), product/specs/<slug>.md (one per area), and a short guide saying how the other three are maintained. Shapes for all four: references/templates.md.

2. Capture a wish

An idea nobody has committed to is one line in the backlog — a slug, a sentence, and an optional dependency note. No estimate, no spec, no roadmap row. Friction here has to stay near zero, or the good ideas go into a chat window instead.

3. Promote before building

Promotion is three edits — two, absent a wish — made before any code:

1. If it started as a wish, replace its backlog line with a graduation tombstone naming where it went (references/conventions.md). Work the user asked for directly never had a line, and skips this edit alone.
2. Append a decision recording which version, and why now.
3. Add the roadmap row and its spec — written from the template for a new area, or this version's behaviors added to the area's existing living spec, never a second file. Either way the spec's Decisions section carries that decision's id and the one-line reason it is cited — the first entry on a new spec, an addition on an existing one, never a swap. An existing spec's header follows its highest linking row from this edit on, not from the build — the compound form in references/conventions.md once a lower row has shipped, plain draft while none has. The new row takes ← we are here only when every row above it has shipped; a building row, or an earlier next row, keeps it.