Architecture Decision Record (ADR)

Trigger phrases: "adr", "architecture decision", "decision record", "why this approach", "why we chose", "why we went with", "nobody remembers why", "why we picked"

When

On an architecture/technology choice that is expensive to reverse, long-lived, or contested (database selection, auth strategy, critical pattern). Small/reversible decisions do not require an ADR.

On a team, the record ALSO goes on the board

docs/ is gitignored in an install, so an ADR written there reaches the machine that wrote it and nobody else — which is the opposite of what a decision record is for. When a teamboard exists, record it with board.sh decide "<title>" "<context + decision + consequences>" as well: the board is shared, so it arrives at every teammate's next session opening, and it travels even when the board lives in its own repository. The local file stays the long form; the board entry is the part that has to reach people, so it must be readable on its own — a title nobody can act on ("auth decided") is not a record.

Format (docs/adr/NNNN-short-title.md, ~1 page)

# NNNN. <Decision title>
Status: proposed | accepted | rejected | superseded (by NNNN)
## Context
Which problem/constraint requires this decision?
## Decision
What was decided (clear, one sentence + rationale)?
## Consequences
Pros / cons / accepted trade-offs.
## Alternatives considered
Why were they not chosen?

Principles

• Invariant: a new decision marks the old ADR as superseded; an ADR is never deleted (decision history is preserved).
• Numbered and dated; keep it short.

Deliberately bypassing a rule is a decision too

A gate the user knowingly overrode — a deferred DoD item, an accepted known gap, a trimmed scope — belongs here whenever its effect outlives the task. It is not a lesser kind of decision: choosing not to apply a rule shapes the codebase exactly as choosing a database does, and it is the one class of decision that leaves no trace in the code at all. Six months on, a rule that was weighed and overridden is indistinguishable from one that was never noticed, and the second is the one you would want to fix.

Record it in the same file as any other decision, with the fields that make it reversible:

## Bypassed
- <gate/rule> — why: <reason> — asked by: <who> — revisit: <condition or date>

revisit is the load-bearing field. A bypass with no condition attached is permanent by default, and nobody chose permanence. See [[confidence-check]], which is where most bypasses surface.

DoD

• Decision + rationale + rejected alternatives recorded; status current.
• Any deliberately bypassed rule is recorded with its reason, who asked, and what would reverse it.