A decision is only recorded
if somebody can tell it still holds.
The folder is full. Twenty ADRs, nine specs, four of them superseded by a decision recorded somewhere else, and at least one describing a service that was deleted last year. Nothing in the folder says which is which.
So the questions a new engineer actually has — is this agreed, is this built, is this still true — get asked in chat instead, answered from memory, and answered differently depending on who is online. The documents were written precisely so that would stop happening.
The usual fix is a status field in front matter, which is a field somebody has to remember to change. It is accurate on the day it is written and decorative within a month, because nothing connects it to the document it sits on top of.
A status that does not notice the document changed underneath it is worse than no status: it is a stale claim wearing a badge.
The parts that matter here
Not the whole feature list — the ones this particular problem turns on.
Two axes, not one
Review state and implementation state move independently, because a spec everyone agreed with and nobody built is a different situation from one half-built and disputed. Collapsing them into a single status loses the distinction that matters most.
Drift is measured against the content
A status remembers the exact version it was set against. Edit the document and it reads validated · drifted, rather than keeping a badge that has quietly stopped being true. A timestamp would fire every time a worker touched a row.
No row until somebody decides
An untriaged document has no status and renders no pill. A folder nobody has reviewed looks like what it is, instead of a wall of drafts implying a process that never ran.
Rejected is a real state
Do not build this is a decision worth recording, and it requires a reason — written as a note in the same transaction as the status, so the refusal and its argument cannot be separated.
Objections live on the heading
A note is anchored to the section it disputes. If that heading is removed the note fails visibly rather than relocating itself onto text that says something else.
The board across a project
Every document carrying a status, in columns you can drag between, filtered by a URL you can paste into a channel before a design review.
What actually happens
- 01An ADR is merged and appears, with no statusIt is in the tree the moment the branch is read. Nobody has triaged it, so it carries no pill — which is the honest representation of a document nobody has looked at yet.
- 02A reviewer reads it and disagrees with one sectionThey leave a note on that heading rather than a comment on a pull request that closed. The note is attached to the text, so it is still there in six months when somebody asks why this was done.
- 03The author revises and the reviewer validatesReview state moves to validated, against this exact version of the text. Implementation state stays where it is, because agreeing is not building.
- 04An agent reads the spec and starts workIt finds the document through search, reads it, and reports that it has started — with evidence saved as a note. It records a claim, never a completion.
- 05Somebody edits the spec three weeks laterThe badge becomes validated · drifted the moment the content changes. Nobody has to notice; the document says so itself, and the agent can ask for the diff between the validated version and the text now.
- 06A person closes the loop, or does notAn agent can say feedback is addressed. Only a person can close it. That asymmetry is the whole reason the layer exists and it is enforced in one function with a test.
What this does not solve
Every page on this site carries one of these, for the same reason: a use-case page with no limits on it is a brochure.
- It will not write the ADR
- This is a reader. You write in your editor and commit, exactly as now — there is no authoring surface and there will not be one.
- It does not model supersession
- ADR-014 supersedes ADR-009 is a relationship between documents and we do not track it. A link and a rejected state is the closest you get.
- Drift fires on a typo
- Content identity is the whole mechanism, so fixing a comma marks a validated document as drifted. Accepted deliberately: the alternative is a rule that guesses which edits count.