Decisions — the load-bearing artefact

Three tests, and a choice needs to pass at least one. Is it expensive to reverse — measured in weeks of work or a data migration, not in an afternoon? Does it serve a named quality goal, so that changing it changes what the system is good at? Does it constrain someone else — another team, a future service, an integration you have not built yet?

A choice that passes none of them is a preference. Do not record it. The fastest way to kill the practice is four hundred documents describing which date library the team likes, because then nobody can find the six that the design actually rests on.

The inverse mistake is rarer and worse: a decision made in a thread, agreed by four people, never written down, and load-bearing for everything built afterwards. That one costs a re-derivation every time a new person questions it, and eventually somebody wins the argument by attrition and reverses it without knowing what it was protecting.

Context: what was true when you decided, including the constraint you were working under. Options: the two or three you seriously considered, each with the reason you rejected it. Decision: one sentence, active voice. Consequences: what gets easier, and what you have now made harder or more expensive. Status and date. And the quality goal it serves.

The rejected options are the section that pays for the whole practice. Two years on, nobody is confused about what you chose — the code says that. They are confused about whether you considered the obvious alternative, and if the document does not answer that, the discussion restarts from zero.

Consequences must include the bad ones. A decision record listing only benefits is marketing, and it removes the one thing a future reader needs: whether the pain they are currently in was known and accepted, or unforeseen. Those two situations call for opposite responses.

Proposed, accepted, superseded, deprecated. An accepted decision is immutable — the moment you edit one to reflect what you now think, you have destroyed the record of what you thought before, and with it every clue about why the current shape of the system exists.

When a decision stops being right, write a new one. Give it a new id, state what it supersedes, and mark the old one superseded with a pointer forward. The old record stays exactly as written. A reader arriving at ADR-0007 is told, in one line, that ADR-0031 replaced it — and can then read both and understand the change.

This is the discipline that separates a decision log from a wiki page. Wiki pages record the present. Decision logs record the sequence, and the sequence is the argument.

Allocate an id once and never reuse or renumber it. That id gets cited from a guardrail, a pull request, a code comment above the ugly workaround, a runbook, and an agent prompt. Renumbering breaks every one of those references silently.

Zero-pad to four digits and stop worrying about it. ADR-0007 sorts correctly in a directory listing, greps unambiguously, and does not collide with a ticket number.

Many decisions are correct only under conditions that will expire. A single Postgres instance is the right call while you are under a few thousand tenants; a shared queue is fine until two teams need different retention.

Write the condition down as part of the decision: "valid while X." That single line is what turns an annual review from an archaeology exercise into a filter — you are checking a handful of stated conditions against reality, not re-reading fifty documents asking yourself whether each one still feels right.

MADR has effectively become the default template, docs-as-code the default location, and Markdown-in-the-repo the default medium. Generators exist for the boilerplate — this site has one — and every serious documentation stack renders a decisions folder without configuration. None of that is a bottleneck any more.

What no tool supplies is the coupling. A decisions folder that nothing else in the repository mentions is a folder of essays, and essays lose to deadlines.

Search your repository for an ADR id outside the decisions folder itself. Guardrail configuration, code comments, pull request descriptions, the runbook, the spec — anywhere.

Zero hits means the practice is decorative, regardless of how many documents are in there. That is the most common result, and it is fixable in an afternoon by adding references rather than by writing more decisions.

Decision to quality goal. Every accepted decision names the goal it serves; every goal can list the decisions taken in its name. This is what makes a decision reviewable — if the goal changes rank, you know exactly which choices are now suspect.

Guardrail to decision. When a decision is worth enforcing, the check that enforces it cites the id. Now the decision has teeth, and a failing build points a developer at the rationale instead of at a rule they will read as arbitrary.

Pull request to decision. One line in the template: which decision does this change rely on, and does anything here contradict one? Most of the time the answer is neither, and it costs five seconds. The occasions when the answer is "it contradicts ADR-0012" are exactly the changes that should not merge on a Friday afternoon.

Local decisions belong in the service that they constrain. Organisation-wide decisions — the identity provider, the event envelope, the deployment target, the language shortlist — belong in one platform repository, published by id, and referenced from the local spine rather than copied into it.

Copying is the failure. Two copies of a decision diverge, and the divergence surfaces during an incident when two teams cite the same id and mean different things.

Assurance regimes across finance, health and AI increasingly ask for documented rationale behind design choices, not just the resulting design. Teams that already keep decision records answer those requests by exporting a folder.

Treat that as a side benefit rather than the motivation. A decision log written to satisfy an auditor is written once, is immediately stale, and is the exact artefact this whole approach exists to avoid.

Ask an agent to add a feature to a system whose architecture it can only infer, and it will infer generously. It will propose the option you rejected, because that option is the most common one in its training data and nothing in your repository says otherwise. It will be articulate about it. It will be wrong in a way that takes a senior reviewer twenty minutes to explain — and the same twenty minutes again next week.

With the decision present and cited, this collapses to nothing. The agent reads that direct database access from other services was rejected in ADR-0009, and it writes the client against the API instead. The saving is not the one prompt; it is the recurrence.

The old failure was documentation drifting behind the code slowly enough that people noticed. The new one is faster: a change that contradicts an accepted decision, generated in seconds, with a plausible commit message and clean tests, merged by a reviewer who never read ADR-0009 either.

Two defences, and you need both. The agent bundle makes reading arch/ and citing the decision part of the workflow before code is written. A guardrail catches the case where it did not. Prose alone is guidance; only the check is enforcement, and this is precisely why decisions and guardrails are adjacent concerns rather than one document.

Agents are genuinely good at the laborious parts of an ADR: enumerating the alternatives, articulating the trade-offs, listing consequences you would have skipped at 6pm. They are not accountable for the outcome, so they do not get to accept one.

The workflow that holds: an agent opens a decision in proposed status when it hits a choice the spec does not cover, and stops. A human accepts, amends or rejects. The status field, which used to be near-ceremonial, becomes the actual control boundary between what the agent may settle and what it may not.

spine.yaml carries the id, title, status, date, the goal served, and the path to the file. Nothing else. An agent scans the index cheaply, then loads only the two decision files relevant to the change it is making.

Context budget is a real design constraint now. A machine layer that inlines the prose forces every agent to read every decision to find one, which in practice means the whole index gets dropped from the prompt and none of it gets read.

When a human reads an edited decision, they lose some history. When an agent reads one, it loses the only evidence that the approach it is about to suggest was tried and failed. Superseding preserves the negative result, and negative results are the scarcest thing in any repository.