FORMAT — SPEC.md house style

The spec, plan and build skills read this before touching SPEC.md. When this doc and a long-standing SPEC.md pattern disagree, match SPEC.md and fix this doc.

Encoding

Dense. Drop articles and filler; fragments are fine. SPEC loads often, so tokens matter.

  • Never compress identifiers, paths, code, numbers or enum values. They stay verbatim.
  • Cite touch points as path/file.ext:line, or by symbol in LIVING docs (lines drift, symbols don’t).
  • One entry reads on its own, without its neighbours.
  • Tag each invariant and bug with the task that introduced it: trailing (T.x). (T.0) = distilled from pre-spec code.

Numbering

  • Monotonic, never reused. §V, §B, §T and §D ids only increase.
  • Retire by striking through: ~~V.7 …~~ RETIRED [YYYY-MM-DD] (T.x). Never renumber, so every V.7 in git history keeps its meaning.
  • New entries go at the end of their section.

Sections

§G Goal · §C Context · §I Interfaces · §V Invariants · §T Tasks · §B Bugs / Backprop · §D Deferred.

§V

- V.<N>: <rule that must hold, stated as a rule, not a task>. Guard: `<test or hook>` | unguarded. (T.<x>)

unguarded is allowed but is recorded debt: a §T row should exist to add the guard.

§T

| # | Task | Files | Depends | Est | Status |
  • Split anything bigger than L along a real seam: T.8a / T.8b.
  • Every non-trivial row has a plan doc: docs/design/tasks/tN_<topic>_plan.md.

§B

- B.<N> [YYYY-MM-DD] <symptom>. **Cause:** <root cause>. **Fix → V.<x> (T.<y>):** <change>. Touches <files>.

Every bug gets a §B entry. A new §V guard is optional but strongly preferred.

§D

Open design questions. When decided, mark inline **RESOLVED [date] (T.x):** … or **Deferred [date]:** …. Never delete: the trail matters.

Discipline

  • spec is the sole mutator. build may flip a §T status cell and nothing else.
  • Show the diff, apply on user OK. Never rewrite a section the user didn’t name.
  • Plans end with “SPEC changes needed”; those are applied only through spec.