# Decision Records

> Numbered, immutable records of accepted decisions — each titled as an assertion, with context, the rule, and honest consequences.

**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](/docs/truth-machine/implementations/flow/), whose
records govern its architecture across forty-plus decisions. Observed in
kin and kinra-os.

## Template

[`templates/decision-records/0000-template.md`](/docs/truth-machine/templates/decision-records/0000-template.md)

## Related patterns

[Change Packet](/docs/truth-machine/kit/change-packet/) is the governed
version of the same instinct, for truth that needs review and exact deltas
rather than narrative.