Skip to main content

Superseding, Amending, and Status Lifecycle

What This Concept Is​

An ADR has a small, deliberate set of status transitions:

  • Proposed - written, under review, not yet binding.
  • Accepted - in effect; the team is bound to this.
  • Rejected - proposed and not adopted; kept for record.
  • Deprecated - was accepted, no longer recommended, no replacement yet.
  • Superseded by ADR-NNN - replaced by a newer decision; the old ADR is read-only.

You never delete an ADR. You mark it, and you link forward to the thing that replaced it. The archive is the asset.

Why It Matters Here​

Lifecycle exists so future readers can reconstruct not just the current decision but the path: what did we try, when did we change course, what was the trigger? "We had a good reason at the time" is rarely recoverable if the reason never shipped.

Amending - updating an ADR in place - is reserved for minor corrections: typos, clarifications that do not change meaning, status updates. Any change that alters the decision or its consequences should supersede instead. Editing an accepted decision without leaving a trail destroys its governance value.

Concrete Example​

The path of a single concern across time.

ADR-0017: Use Elasticsearch for full-text product search. Status: Accepted 2024-05-02. Superseded by ADR-0048 on 2026-03-14.

ADR-0048: Migrate product search to OpenSearch. Status: Accepted 2026-03-14. Supersedes ADR-0017. Context: Elasticsearch's license change conflicts with our distribution model. We verified OpenSearch compatibility over a 6-week spike. Decision: Migrate to OpenSearch 2.x. Keep index schema unchanged. Cut over behind a feature flag. Consequences: - drop Elasticsearch-only plugins; + keep FOSS licensing; + ops team retraining minimal.

Both ADRs remain in the repo. ADR-0017 now has, in its Status section, an explicit link: Superseded by ADR-0048 (2026-03-14). If a reader lands on ADR-0017 first, they are one click away from the current state.

Common Confusion / Misconception​

"Delete outdated ADRs." No. Mark and link forward. The discarded decision is part of how the team thinks; deleting it discards the reasoning trail.

"Just edit the ADR in place when things change." This silently invalidates the record. Someone who read ADR-0017 two years ago will point to its old text; the new text will not match their memory. Supersede instead.

"Deprecated and superseded are the same." They are not. Deprecated means "do not rely on this going forward, we have not built the replacement yet." Superseded means "ADR-X is the replacement, here is the link."

How To Use It​

When replacing a decision:

  1. Write the new ADR. Link back to the old one in its Context.
  2. Update the old ADR's status to Superseded by ADR-NNN (YYYY-MM-DD).
  3. Do not rewrite the old ADR's Context, Decision, or Consequences. It was correct at the time.
  4. Add a single note at the top of the old ADR if needed: "See ADR-NNN for the current decision."

Small amendments (typos, status transitions, formatting) are fine in place. The rule is: if a future reader looking only at the ADR would now misunderstand the original reasoning, you are editing too much - supersede.

Check Yourself​

  1. Why is it unsafe to silently edit an Accepted ADR to reflect a new decision?
  2. What is the difference between Deprecated and Superseded, and when would you use each?
  3. Your team has an ADR whose Decision still holds but whose Context is now wrong (constraints changed). Amend or supersede? Defend the choice.

Mini Drill or Application​

Find a decision in your system that has effectively been overridden but where no superseding ADR exists. Write both:

  • the replacement ADR, with proper Context referencing the original
  • the one-line Status update on the original ADR

Commit both in a single PR titled "Supersede ADR-X with ADR-Y."

Read This Only If Stuck​