checklist · adr ≥2 options including do-nothing
ADR · ≥2 options including do-nothing
Read in 60 seconds before signing the ADR. Any line that cannot be checked sends the ADR back to Proposed.
TIP
The single most common ADR failure is the one-option ADR (an announcement disguised as a decision). The third option, do nothing, is the corpus's discipline against pretending no choice was made.
Status discipline
[ ] ADR opens as Proposed.
because:the team reads and reacts before code lands — Practice · Step 2[ ] Code on the chosen path has not yet been merged.
because:ADRs written after code describe what was, not why we chose — Evidence · Practice
Considered Options — the gate
[ ] At least two options are listed.
because:an ADR with one option is an announcement — Clinic[ ] Do nothing is listed as an explicit option.Do nothing = ship the cycle without solving this, with named consequences.
because:the discipline of writing do nothing honestly often changes the chosen option — Practice · Step 5[ ] Each option is a real alternative. Not the framework we already use vs something we made up to fill the slot.
Options Analysis — pros AND cons
[ ] Every option has pros AND cons listed.
because:Options Analysis as one positive sentence is endorsement, not analysis — Clinic[ ] Each con is anchored in a Decision Driver. If a con doesn't connect to a named driver, either the driver is missing or the con is decorative.
Decision Outcome — the trade-off lives here
[ ] The chosen option is named with rationale. One paragraph, anchored in the top driver.
[ ] Trade-offs explicitly accepted are named — in Decision Outcome, not in Consequences.
because:trade-off ≠ consequence — Clinic · Point 3[ ] The boundary of the precedent is named if narrow.This ADR is/is not a precedent for [other situations] — explicit.
Sign-off
[ ] Two engineers sign. Author + one reviewer (typically another senior or the TL of an adjacent service).
[ ] Status moves from Proposed to Accepted on sign. ADRs that linger in Proposed are dead.
If any line cannot be checked, the ADR returns to Proposed. The code on the chosen path does not land until the gate passes.
See also
- Practice — Writing ADRs
- Template — ADR (MADR format)
- Canon — What We Shape · ADR
- Clinic — An ADR with one option