Introduction · 1 minute

Architecture Decision Records

Decisions get replaced. The record of them shouldn’t have to be rewritten.

Teams record architecture decisions as they make them, and later decisions replace earlier ones. Keeping track of which decisions still stand is a linking problem, and office documents and wikis don't have the tools to solve it. Standards from the XML world do. Two working demos show how.

Use casesWatch the explainer (1:30)The problemThe principlesThe demosBeyond software

Use cases

See it working

Each example answers the same question for a different kind of record: what applied on a given day, what replaced it, and why.

Software development

Other sectors

In 90 seconds

The idea, explained

How decisions get replaced, why Word, Google Docs and Confluence struggle to track it, and how XML linking standards keep the records untouched while the current specification is computed. The rest of this page covers the same ground in detail.

Part one

Why supersession matters

An Architecture Decision Record (ADR) captures one decision: what was decided, by whom, when and why. ADRs are meant to be written once and kept. The interesting part starts a year later, when some of them are no longer true.

January: PostgreSQL is the datastore. Primary keys are UUIDv4.

April: keys move to UUIDv7. The PostgreSQL decision, in the same record, still stands.

May: events go over LISTEN/NOTIFY. November: Kafka. The following March: NATS.

September: one identity decision replaces three earlier ones, spread across two records.

After a few cycles of this, anyone reading the decisions needs answers to a few questions. A new engineer wants to know what's in force today. An auditor wants to know what was in force on the day of the incident. A reviewer wants to know whether a new proposal contradicts something already agreed. An AI coding agent given the folder needs to know which of these statements to obey. A record that's been replaced but isn't marked as such is worse than no record, because it is still confidently telling people what to do.

The question is always about relationships between decisions: this one replaces that one, partly or in full, from this date. Those relationships are where ordinary documentation tools break down.

Why it’s hard in Word, Google Docs and Confluence

What you needWhat document tools give youThe XML standard for it
Point at one decision inside a record Links reach a file or page, or a heading anchor that changes when someone retitles the heading. xml:id and XPointer address an individual element, durably.
Leave old records untouched The only place to say “superseded by ADR-12” is a status field inside ADR-7 itself, which means editing history, and someone has to remember to do it. XLink linkbases store links outside the documents they connect.
Say what kind of link it is Links are untyped, or typed with a tool-specific label (Jira’s “relates to”) that nothing outside the tool understands. Arc roles are URIs from public vocabularies, such as Dublin Core’s dcterms:replaces.
One change ending several decisions Edit each old page separately, and hope they all stay consistent. One XLink extended link can join many ends with a single arc.
“What did we believe on 30 June?” Version history is per document. Rebuilding a consistent picture across forty pages at one date is archaeology. Arcs carry dates; an XSLT transform takes the date as a parameter.
A current specification with no stale decisions Written and maintained by hand, so it drifts from the records. XSLT follows the links and generates the spec, every time.
Catch broken or contradictory links Nothing checks them. Broken links surface when a reader trips over one. Schematron rules, with failures reported in plain sentences.

To be fair to the tools: Word’s Track Changes, Google Docs’ version history and Confluence’s page history are good at what they do, which is recording edits to one document. Supersession isn’t an edit to a document. It’s a fact about two or more documents, and those tools have nowhere to keep it except inside one of the documents involved. A team can bolt something together with page properties, macros and discipline, but it’s a local convention someone has to maintain, not a standard.

The XML world solved this decades ago

These standards were designed in the late 1990s and 2000s for publishing, legislation and aerospace documentation, where cross-referencing parts of many documents and tracking amendments is the everyday job. They are ratified, stable, and have several independent implementations, and they were designed to work together.

Part two

The principles behind the demos

Both demos use different examples (an order service and a billing platform), but they follow the same principles.

Decision records and a linkbase feed a transform that produces the current spec, a past spec, JSON, and a validation report. Decision records adr-0001.xml … adr-0009.xml Written once. Never edited. No links to each other. Linkbase XLink arcs: new → old, role dcterms:replaces. Append-only. XSLT transform follows the links, computes status, parameter: as-of date Spec as it stands today Spec on any past date JSON · SVG timeline Schematron report “ADR-2 can’t replace ADR-6…”
The sources are the records and the linkbase. Everything a reader looks at is generated from them, so the generated views can’t drift out of step with the sources.
  1. Records are immutable

    An accepted decision is never edited. Not to flip a status, not to add a “superseded by” line. Each ADR stays exactly as it was on the day it was decided.

  2. Relationships live outside the records

    Every “this replaces that” is an XLink arc in a separate linkbase. Recording a new decision means one new file plus one appended arc. No existing file changes.

    <!-- ADR-0004 replaces one decision of ADR-0001; PostgreSQL still stands -->
    <supersession xlink:type="extended" xlink:title="UUIDv7 keys">
      <loc xlink:label="new" xlink:href="adr-0004.xml#adr-0004-d1"/>
      <loc xlink:label="old" xlink:href="adr-0001.xml#adr-0001-d2"/>
      <arc xlink:from="new" xlink:to="old"
           xlink:arcrole="http://purl.org/dc/terms/replaces"/>
    </supersession>
  3. Point at decisions, not documents

    One record often holds several decisions. Pointers name the exact decision (or clause) being replaced, so the rest of the record stays in force.

  4. Status is computed, never stored

    Nothing in any ADR says “superseded”, so nothing can go stale. Whether a decision is in force is worked out from the links every time a view is built.

  5. Time is a parameter

    “What was in force on 30 June?” is the same transform with a different date. The same files produce the past view and the present one.

  6. Borrow vocabulary; mark what’s local

    Link types are URIs. Where a public one exists it is used: dcterms:replaces for supersession, prov:wasInfluencedBy for the requirement that drove a change. Anything invented locally is named as such.

  7. Superseded decisions are kept, struck through

    Retired decisions don’t vanish. They are shown struck through, with what replaced them and when, so the reasoning behind today’s design is still there to read.

  8. Check the links

    Links can be wrong: a pointer to nothing, a decision replacing a newer one, two decisions both claiming to replace the same thing. Schematron rules catch these and explain each one in a sentence.

Part three

The demonstrations

Each demo is a separate, self-contained build. Their source XML is published alongside, so you can read the records and the linkbase directly.

Demo 1 · Order Service

A computed specification, with validation

Nine ADRs and one linkbase, turned into a technical specification by XSLT 3.0 (Saxon). Each decision in force shows, in the margin, what it replaced and what that replaced.

  • Partial supersession: one decision of a record replaced, its sibling kept
  • One arc replacing three decisions across two records
  • A three-step chain: LISTEN/NOTIFY → Kafka → NATS
  • A proposed ADR shown as pending, not applied
  • The same spec as it stood on 30 June 2025
  • Schematron validation of a deliberately broken linkbase
  • The same model exported as JSON
Open the specification →

Spec on 30 June 2025 · Linkbase · An ADR · Validation report · JSON · README · Download source

Demo 2 · Billing Platform

Time travel with a date slider

Ten ADRs and a dated decision log. Move the slider and the specification and a supersession timeline are recomputed for that day, in your browser. No source file changes.

  • Each link records the date it takes effect
  • A two-step chain that resolves to the current decision
  • One arc retiring two decisions together
  • Amending a single clause, with the rest of the record still in force
  • Withdrawal with no replacement, which a “superseded by” field can’t express
  • Each change linked to the requirement version that drove it
Open the interactive spec →

Decision log · An ADR · Requirements · README · Download source

How the two differ

Demo 1Demo 2
GranularityIndividual decisions inside a recordWhole records, plus named clauses
Linkbase shapeOne extended link per supersessionOne extended link for the whole log
TimeEach ADR’s decision dateAn effective date on each arc
Kinds of linkReplacesReplaces, amends, withdraws, was influenced by
Where it runsBuilt ahead of time with XSLT 3.0XSLT running live in the browser, in SaxonJS
ValidationSchematron rules and reportNot included; noted as the next step

Part four

Beyond software

ADRs are one case of a general problem. Any organisation that revises policies, procedures or approved designs gets asked what applied on a particular day, what replaced it, and why. The same model, immutable records with dated replaces, amends and withdraws links kept outside them, answers that in regulated sectors too.

Sector examples · UK

Policies that know what replaced them

Four worked examples, each with a date slider, a timeline of changes and preset questions an inspector or auditor might ask.

Open the sector examples →

How it works · Talk about your sector