What does the Status field of an Architecture Decision Record track, and what is the rule about editing a record once it has been accepted?
answer
- Proposed / Accepted / Rejected / Deprecated / Superseded-by
- Superseded = replaced & linked; Deprecated = no successor
- Accepted ⇒ append-only: typos and status only
- Bidirectional links + never reuse numbers
- Generated index shows what's actually in force
basics
~20 sStatus shows where a record stands: Proposed, Accepted, Rejected, Deprecated, or Superseded by a newer record. Once accepted, the record is essentially immutable — to change the decision you write a new record and mark the old one superseded, so the history survives.
solid answer
~50 sThe Status field makes the decision log navigable: it tells a reader which records are currently in force. Typical values are **Proposed** (drafted, under discussion), **Accepted** (in force, implementation may proceed), **Rejected** (evaluated and declined — kept so the question has a citable answer), **Deprecated** (no longer recommended, with nothing replacing it — e.g. the component was removed), and **Superseded by ADR-00NN** (replaced by a specific newer record). Once a record reaches Accepted it becomes effectively **immutable**: allowed edits are typos, formatting, and status transitions plus links to successors. A changed decision is expressed as a *new* record whose Context explains what changed, with a bidirectional link (old says "Superseded by 0031", new says "Supersedes 0012"). This append-only discipline is what makes the log a ledger of reasoning over time rather than a wiki page showing only the present. The cost is that readers must follow chains, which is why teams maintain an index listing current status per record.
go deeper
List the states and say that accepted records aren't edited — you write a new one and mark the old superseded.
Distinguish Deprecated from Superseded, insist on bidirectional links and never reusing numbers, and explain why immutability preserves the reasoning chain.
Add operations: a generated index so readers see current policy, sweeping stale Proposed drafts, handling reaffirmations and partial amendments, and detecting log-versus-reality drift.
Own the acceptance rule itself — who may move a record to Accepted, how that meshes with an advice process or architecture group, and how accepted decisions get enforced (architecture tests, fitness functions) so the log stays true rather than aspirational.
## What the Status field is for A decision log accumulates. After three years it may hold 60 records, of which perhaps 40 are still in force. A reader arriving at record 0012 must be able to tell in one line whether they are reading current policy, a historical position, or a draft nobody agreed to. That is the Status field's only job — and it is why every ADR template, from Nygard's original to MADR, puts it near the top. ## The standard states | Status | Meaning | Typical trigger | |---|---|---| | **Proposed** (a.k.a. Draft / Pending) | Written, circulated, not yet agreed | Author opens a pull request or RFC | | **Accepted** | In force; the team is bound by it | Agreement reached by whatever the team's acceptance rule is | | **Rejected** | Evaluated and declined | The proposal loses; record is kept, not deleted | | **Deprecated** | No longer recommended, but nothing replaces it | The subsystem it governed was deleted; the constraint simply no longer applies | | **Superseded by ADR-00NN** | Replaced by a specific newer decision | A new ADR decides the same question differently | Some teams add **Proposed → Under review**, or an explicit date and decider on the Accepted line ("Accepted 2026-02-11 by the platform team"). Some add **Amended by ADR-00NN** for the case where a later record refines rather than replaces (e.g. narrows the scope of the original rule). Keep the vocabulary small and defined somewhere central; a status value nobody can define is noise. **Deprecated vs Superseded** is the distinction most often muddled. *Superseded* means: the same question was answered again, differently — follow the link. *Deprecated* means: the question stopped mattering, or the decision is discouraged with no replacement to point to. If there is a successor, always use Superseded and link it. ## The immutability rule Once a record is Accepted, treat it as **append-only**: **Allowed** — fixing typos and broken links, formatting, adding the status transition, adding links to superseding/amending records, appending a dated note ("2026-07: see ADR-0031"). **Not allowed** — rewriting the Decision, editing Context to match how things turned out, quietly deleting a consequence that proved embarrassing, or renumbering. ### Why this rule exists 1. **The log's value is historical.** A record that is edited to stay current answers "what do we do now?" — which the code already answers. The unique thing an ADR gives you is "what did we believe, and why, at the moment we committed?" Editing destroys exactly that. 2. **Superseding preserves the reasoning chain.** ADR-0031's Context typically consists of ADR-0012's negative consequences finally biting. If 0012 was overwritten, 0031's reasoning becomes unverifiable. 3. **Citations must stay stable.** Code comments, pull requests, runbooks and other ADRs reference records by number. Mutable content behind a stable citation is a trap. 4. **It changes behaviour.** Knowing a record is permanent makes authors more careful and more honest at writing time. ### Practical consequences of immutability - **Numbers are never reused**, even for rejected or withdrawn drafts. A gap in the sequence is harmless; a reused number breaks every citation. - **Links are bidirectional.** The old record names its successor; the new one names what it supersedes. One-directional links leave readers who land on the old record believing it is current. - **A partial change is still a whole new record.** If only one clause of a decision changes, write a new record that states the full current decision and supersedes (or amends) the old one. Patching a sentence in place is the failure mode this rule exists to prevent. - **An index is required in practice.** A generated `README.md` in the ADR directory listing number, title, status and successor lets readers see current policy without walking chains. Tools such as `adr-tools` (a small shell CLI implementing Nygard's conventions) generate this and the supersede links automatically; `log4brains` and MADR-based generators publish a browsable static site. - **Stale Proposed records are a real smell.** A draft sitting in Proposed for a year means the decision was made informally or abandoned. Sweep them periodically: accept, reject, or withdraw. ## Who moves a record to Accepted? The status vocabulary is useless without an agreed **acceptance rule**, and this is a team/organisation choice, not a template one. Common rules: approval by the team that owns the code (ADR merged via pull request with N approvals); sign-off by an architecture group; or, in an *architecture advice process*, the decision-maker accepts it themselves after demonstrably seeking advice from those affected and from people with expertise. Write the rule down — often in ADR-0001, the record that establishes the practice. ## Edge cases worth knowing - **Reaffirming a decision.** Re-examining a decision and keeping it is a legitimate outcome. Record it as a new ADR that supersedes the old one with the same decision plus updated Context, or as a dated note on the original. Either way the re-examination itself is valuable information. - **Decisions accepted but never implemented.** If reality diverged, the log is lying. Either implement, or write a superseding record admitting the change. Periodic drift checks — ideally automated architecture tests derived from the decisions — are what keep the log truthful. - **A superseding chain of three or more.** 0004 → 0019 → 0031 is normal and healthy; it is a visible history of learning. The index is what stops it becoming a maze.
- How does a reader tell which decisions are currently in force in a log of 60 records with several superseding chains?Through a generated index — usually a README in the ADR directory listing number, title, date, status and successor link — rather than by reading records in order. Tools like adr-tools or log4brains generate it from the files, so it cannot drift. Without an index, immutability becomes a usability problem: readers land on superseded records and act on stale policy.
- A decision was accepted, but the team never implemented it and did something else. What is the correct fix?Do not silently edit the accepted record. Either implement it, or write a new ADR that records what was actually done, explains in its Context why the original was not followed, and supersedes it. The unimplemented record stays in the log — the divergence itself is useful information, and hiding it makes every other record less trustworthy.
Think of legislation rather than a policy wiki. A repealed statute is not erased from the statute book — it stays on the record, marked repealed, with a pointer to the act that replaced it. Courts and historians both need the old text; only the index tells you what is currently in force.
saying these in an interview costs you the question
- Editing an accepted record's Decision text to reflect a new choice instead of superseding it
- Using Deprecated when a specific successor record exists (that is Superseded by, with a link)
- One-way supersede links, so readers landing on the old record think it is current
- Reusing an ADR number after a draft is withdrawn, breaking existing citations
- Letting drafts sit in Proposed indefinitely, which means decisions are really being made off the record
- Defining status values nobody has written down, so "Approved", "Final" and "Accepted" coexist with unclear meanings