The Computing Series

The ADR Lifecycle

                              ┌─────────────┐
                              │  PROPOSED    │
                              │  (has owner, │
                              │   has date)  │
                              └──────┬──────┘
                                     │
                                     ▼
                              ┌─────────────┐
                              │  DISCUSSED   │
                              │  (tradeoff   │
                              │   named,     │
                              │   AT# cited) │
                              └──────┬──────┘
                                     │
                          ┌──────────┴──────────┐
                          ▼                     ▼
                   ┌─────────────┐       ┌─────────────┐
                   │  ACCEPTED   │       │  REJECTED   │
                   │  • tradeoff │       │  • reason   │
                   │    named    │       │    stated   │
                   │  • reversal │       │  • alt.     │
                   │    condition│       │    chosen   │
                   │    stated   │       └─────────────┘
                   └──────┬──────┘
                          │
                          │ (conditions change)
                          ▼
                   ┌─────────────┐
                   │  SUPERSEDED │
                   │  • links to │
                   │    new ADR  │
                   │  • explains │
                   │    what     │
                   │    changed  │
                   └─────────────┘

 ACCUMULATION: Accepted ADRs form the system's decision log.
 Each ADR is a layer in the geological record of the architecture.

 FAILURE PATH: ADR written post-hoc → tradeoff never discussed
 → reversal condition absent → decision relitigated every quarter
 → FM8 (Contract Violation) when downstream teams infer
 guarantees that were never made

An ADR that lacks a reversal condition is not a decision record — it is an announcement. The lifecycle matters because accepted decisions accumulate as the system’s geological record: each layer constrains what the next layer can do. A superseded ADR that does not link to its replacement creates a gap in the record, and engineers who find the original ADR without the supersession will build on a foundation that no longer exists.

Read in the book →