Superseding a Decision
The correct way to change an accepted architectural decision without destroying history.
Why
When you edit an old ADR in place, you erase the reasoning that was valid at the time, and future archaeologists cannot understand why the architecture took the shape it did. Superseding preserves the original as a historical artifact and adds a new ADR that explains what changed and why. This matters during incident reviews: often the root cause is 'we changed X but didn't update the decision record', and a clean supersede chain makes that visible instead of invisible.
When
Whenever an Accepted decision is being reversed or significantly amended. Takes 20 min. Never skip — in-place edits are the #1 cause of stale architecture docs.
How
1. Create a new ADR with the next number (do NOT edit the old one) 2. In the new ADR's Context, link the old one: "Supersedes ADR-0007" 3. Explain what changed in the world that invalidates the old decision 4. State the new Decision and its Consequences 5. Open the old ADR and change ONLY its Status line: "Status: Superseded by [ADR-0012]" — leave the rest untouched 6. Commit both files in the same PR with message "supersede ADR-0007 with ADR-0012"
Example
Old ADR-0007 (PostgreSQL) is now too slow for the events path.
New ADR-0012:
- Status: Accepted
- Context: Supersedes ADR-0007. The events write path hit 50k writes/s;
Postgres WAL cannot keep up. The transactional billing store stays on
Postgres (ADR-0007 still valid for that scope).
- Decision: **Route event writes to ClickHouse; keep Postgres for billing.**
ADR-0007 updated:
- Status: Superseded by [ADR-0012] (event path only; billing unchanged)Common Problems
- ⚠Superseding without explaining what changed in the world — the new ADR reads as a preference, not a response to new information.
- ⚠Marking the old ADR 'Deprecated' instead of 'Superseded by' — Deprecated is ambiguous; the explicit link is what makes the chain navigable.
Best Practices
- ✓Scope the supersede precisely — 'event path only' is more useful than a blanket 'we switched off Postgres'.
- ✓Add a one-line TL;DR at the top of the new ADR so skimmers grasp the change without reading the full context.
- ✓If a decision is superseded more than twice, schedule a architecture review — repeated churn signals an unstable foundation.