guillevc Record
The single writer of the living spec: the glossary (what words mean, edited in place) and ADRs (what was decided, immutable, reversed only by superseding).
Gates
- Autonomous: classify the fact, choose the slot, draft the entry.
- Light: glossary edits; confirm before writing.
- Hard: a committed ADR is immutable. Present the draft, get explicit go-ahead, then write. Never edit a committed ADR in place; reverse it only by superseding. An uncommitted ADR is still soft; see Soft ADRs below.
Route
Durable-fact test: does this change a rule, design, decision, or term? If not, it's behavior or progress; leave it to code and tests, stop. If so:
| Fact | Slot |
|---|---|
| a term (project vocabulary) | glossary entry |
| a decision / rule / constraint / design / deviation | a new ADR (supersede if it reverses one) |
Locations: glossary docs/GLOSSARY.md; ADRs docs/decisions/; else the agent doc
(CLAUDE.md/AGENTS.md); else ask. Create lazily on first entry.
Glossary
One canonical term per concept. Terms only. A relationship ("an Order owns its line items") is a decision, so it's an ADR. Before writing a term, check the existing glossary; if it collides with or duplicates an entry, surface the conflict for the human instead of writing a rival.
**Term**:
One or two sentences. What it IS, not what it does.
_Avoid_: synonym1, synonym2
ADR
# <NNNN>: <decision stated as a choice>
Supersedes: <old-id> <!-- only when this reverses an existing ADR; else omit -->
Status: superseded by <id> <!-- only on an ADR that was later reversed; a live ADR has none -->
<1-3 sentences: context, decision, why.>
## Considered options <!-- optional; add only when it earns its place -->
## Consequences <!-- optional; add only when it earns its place -->
Number by incrementing the highest id in the dir. A new ADR has no Status line, which means live.
Never write Status: accepted; the only status ever written is superseded by <id>.
Record an ADR only when all three hold: hard to reverse, surprising without context, a real trade-off. Else skip.
Soft ADRs. An uncommitted ADR is still soft: edit or drop it in place, no supersede, no merits gate. Immutability starts at the commit that delivers it. Once committed, the ADR is immutable. Treat an ADR as immutable and supersede unless you're sure it's still uncommitted.
Supersede to reverse a committed ADR. First the merits gate: argue the reversal fresh, as if
no ADR existed, never "the old one is inconvenient." If merits favor change, draft the new ADR with
its Supersedes line and flip the old one's Status, never touching the old body.
Write both or neither; else keep the old and record nothing.
Steps
- Restate the fact in one sentence; run the durable-fact test and route it.
- For a reversal, run the merits gate, then the three-test gate.
- Draft in the slot's format.
- Confirm (hard gate for ADRs), then write. One fact, one home.