Decision records

September 16, 2026 · View on GitHub

A steering veto list. Open the list below before proposing a new primitive, surface, or storage home. Architecture docs and code describe how the system works today; this folder records product-shaped decisions already made, usually a no with a revisit-if.

Linked from AGENTS.md for that check — not as homework and not as a museum.

A good record is half a page: context, the decision, consequences. See 0025 for the shape that actually steers (write the no before the next agent re-proposes the primitive).

Decision records are point-in-time documents, so they are exempt from npm run docs:check-temporal; everything else in docs/ describes current behavior (see documentation principles).

When to add a record

Write one after you have already decided not to build something the next agent will otherwise re-propose. Copy 0000-template.md to the next unused number (read this index on main first) with a kebab-case slug. Keep it to roughly half a page.

Do not write an ADR on every PR. Number collisions (two 0022s, then two 0028s, then two 0029s the same day) are the failure mode of that habit. If a number collides, renumber the later record; do not leave duplicates. npm run docs:check-decisions (part of npm run validate) rejects duplicate primary numbers. A lab note may share a number only as NNNN-*-lab.md.

Do not record layout or UI tweaks, mode assignments, or "we use library X" unless that pick is a no that will otherwise be re-litigated.

When a later record changes a decision, mark the old one superseded by NNNN rather than editing or deleting it, and list it under Historical / UI / implementation.

Add new steering records to the steering list, not a catch-all numbered dump.

Steering list

Open these before proposing a new primitive, surface, or storage home.

Historical / UI / implementation

Accepted or superseded records that do not change the next product proposal. Do not treat this list as homework. History stays; it is not silently deleted.