Decision Records

Tier: 0 · Normative weight: ergonomics Requires: nothing

Problem it removes

Decisions live in chat threads and heads. Six months later the constraint is still enforced but nobody remembers why, so it gets re-litigated — or silently violated by someone who never knew it existed.

Mechanism

A docs/decisions/ directory of NNNN-kebab-title.md files. The H1 titles the decision as an assertion, not a topic — “One client over a JSON API,” not “API design.” A plain Status: accepted, YYYY-MM-DD line follows, then an optional relationship paragraph stating what earlier decisions this amends and what it explicitly does not touch. Sections: Context (the tension that forced the decision), Decision (the rule, one bolded sentence, then elaboration), Consequences (including honest negatives — what now exists, what still does not).

Records are immutable once accepted; a change of mind is a new record that names its predecessor. If a superseded record still holds a live contract, the successor absorbs it before the predecessor is deleted — a decision’s only written home must never disappear while code depends on it.

Cost

Authoring: half an hour per decision, paid once at the moment the context is freshest. Per change: none — records do not rot because they never claim to be current. Per session: reading two or three relevant records replaces an archaeology session.

Do not adopt when

Decisions are cheap and reversible enough that Git commit messages already carry the why.

Evidence

Assessed in flow, whose records govern its architecture across forty-plus decisions. Observed in kin and kinra-os.

Template

templates/decision-records/0000-template.md

Related patterns

Change Packet is the governed version of the same instinct, for truth that needs review and exact deltas rather than narrative.