ADR-NNN:
Copy this file to
docs/adr/NNN-kebab-title.md(next free 3-digit number — seeREADME.md) and fill every section. The two project-specific sections — Reversal-Trigger and Why-this-matters-to-a-future-maintainer — are mandatory and must never be left empty (AR-21). An ADR without them is a decision log entry; with them it is a legibility artifact: it tells whoever inherits this code not just what was chosen, but what would make it wrong and what they break if they don’t understand it. "Solo for now, legible for later."
Status: Proposed |
Accepted |
Superseded by ADR-NNN — (date: YYYY-MM-DD) |
Context
The forces at play: the problem, the constraints, the alternatives on the table, and what makes this a real decision rather than an obvious default. Link the source discussion (architecture.md §…, an epic, a pre-mortem item) rather than restating it.
Decision
What we chose, stated plainly. Include the concrete shape (crates, libraries, topology) where it aids a reader.
Consequences
The trade-offs accepted — what gets easier, what gets harder, what we deliberately gave up. Note any sub-decisions this enables or forecloses.
Reversal-Trigger
(Mandatory.) The concrete, observable signal that would make us revisit or undo this decision — not "if it turns out bad" but a specific condition: a measured threshold crossed, a dependency dying, a constraint changing. If a future maintainer sees this signal, they have explicit permission to reopen the decision.
Why-this-matters-to-a-future-maintainer
(Mandatory.) What a maintainer who inherits this loses if they don’t understand it — the foot-gun they’ll step on, the invariant they’ll unknowingly break, the "why didn’t they just…" that has a real answer. Write it for the person who arrives two years from now with no memory of this conversation.