decision-records

A decision record is a numbered, dated document saying what was chosen and why. Teams adopt them, write ten, and then lose the two properties that made them worth having.

They collide on numbers, because the obvious way to pick the next one reads what has landed, and the number you need is claimed by work that has not landed yet.

They get quietly rewritten. Someone learns the decision was wrong and improves the record — and now the document says the team chose the thing it actually chose second. The reasoning that produced the original is gone, along with any way to learn from having been wrong.

Both have cheap structural fixes.

The lifecycle

take a number  ->  publish it  ->  write the record  ->  accept  ->  amend, dated
   (against         (before        (decision, context,    (Decision    (append only,
 everything          you             consequences,         freezes)     in place)
  in flight)         write)          what would falsify it)

Five rules hang off that, and the first two are about the same ninety minutes.

1. Take the number against everything in flight, not everything that landed

Read three places and take one past the highest any of them claims: your working tree, the trunk, and the files changed by every open pull request.

Reading the trunk alone is what produces collisions. We had two authors take the same number on one afternoon — both used the tool, both reads were correct when made, and both produced the same number.

Two properties are deliberate, and both are refusals:

Gaps are never filled. The next number is one past the highest claimed, never the lowest unused. A gap usually means a number was referenced somewhere before being abandoned or renumbered, and reusing it silently repoints an old reference at a new decision — a worse failure than a wasted integer, and much harder to see.

It reports; it does not reserve. No registry file, no lock. A reservation scheme has to decide when an abandoned claim expires, and it becomes a second source of truth able to disagree with git. The set of in-flight numbers already exists — it is the open pull requests. So look at it rather than mirroring it.

2. Publish the number before you write the record

This is the rule people skip, and it is the one that actually closed our collision.

The open-PR check above is only as good as what has been published. We assumed the exposure window was the gap between pushing and opening a PR — short, and closing automatically. Measuring the collision showed otherwise: the winning PR was open for three minutes before it merged, at the very end of the work.

In practice a record is written, revised and gated on an unpushed branch for the whole session. The number is taken at minute zero and published at minute ninety. The window is not the push-to-PR gap; it is the entire authoring session, during which the rung that would have caught the collision had nothing to look at.

So: the moment you take a number, push the branch as a draft pull request whose title names it. Body empty. Then write.

It is not reservation, and that is the point — it has no release problem. Close the draft and the number is released and never reclaimed, exactly as the gap rule requires. It does not close the window either: two people running the tool in the same minute still collide. It shrinks a ninety-minute target to a sixty-second one with machinery that already exists.

3. An accepted Decision is frozen — and only the Decision

Once a record is accepted, its ## Decision section is a historical record of what was chosen. Two sanctioned moves, and no third:

• Annotating what happened next → a dated note in Consequences, or a dated marker inside Decision: _(Amended 2026-05-05: the way was renamed.)_. Append-only. In-place amendment is the prescribed mechanism, not a workaround.
• Reversing the decision → a new record that supersedes this one.

Every other section — Context, Consequences, Observability — stays fully editable, so typo fixes and follow-up notes need no ceremony.

The date is not decoration. It is what makes an amendment a record rather than a note, so an undated marker is refused like any other new prose. That is enforced below, and it is worth enforcing: an undated "Amended" is indistinguishable from someone editing the decision and labelling it politely.

4. Name what would tell you this was wrong

A decision that affects behaviour names, in the record, how you would know: what it emits, what you will measure, and against what baseline — or an explicit, reasoned n/a.

The n/a matters as much as the measurement. An empty section reads as nobody got to it; a reasoned n/a reads as we thought about it and here is why there is nothing to measure, and a reader can disagree with the second.

5. A sentence that promises future work names its disposition

Every "we'll do this later" carries one machine-checkable line:

Follows-up: <work-item-id>
Follows-up: deferred — <the trigger that would reopen it> (<date>)
Follows-up: none — <why this needs no work> (<date>)

Silence is the one shape refused. A deferral with a named trigger is a fine answer. A none with a reason is a fine answer. A promise with nothing after it is how a record accumulates work nobody owns, and it reads identically to work in progress.

The deviation protocol

The rule that makes all of the above fire at the right moment. When you find an error, a contradiction, a missing field, or a better approach:

1. Do not silently deviate.
2. Take a number, publish it, write the record.
3. Make the smallest correct change.
4. Update the affected docs in the same commit, referencing the record.

The trigger is worth memorising: when you notice you are about to make a judgment call, that is the moment the record is owed — not after the work, when you will remember the conclusion and not the alternatives.

The script

./adr.py next  [--dir DIR] [--root DIR]              # the next free number
./adr.py check [--dir DIR] [--base REF] [--root DIR] # refuse a rewritten Decision

Python 3.8+, stdlib only. git required for check; gh optional for next.

next degrades loudly

Without gh, unauthenticated, or offline, it still answers — with the highest landed number — and says so on stderr:

! open pull requests were NOT consulted (no git remotes found).
  This number is one past the highest LANDED record. Someone may already
  hold it on an open branch. Check by hand, or publish yours immediately.

Authoring must not require the network. A silent degrade would reinstate the exact blind spot the open-PR rung removes, so the degrade is never silent. It prints the publish-now instruction on every run, including the good one.

check reads a diff, and judges renames

For every record already accepted before this branch, ## Decision must be unchanged or changed only by adding dated markers.

Records that become accepted in this very change are exempt — they are being authored, not amended — and a genuinely new accepted record always passes, because writing a superseding record is the remedy this gate prescribes. Refusing new files would break its own escape hatch.

The rename that takes the whole rule off

A rule like this loops over a diff and compares each file's before and after. A file that was renamed in the same diff has, depending on how git reports it, no before side to compare against — so renaming a record and rewriting its Decision in one commit is not judged at all. One git mv and the rule is gone, silently, with the gate still green.

Measured precisely, because the usual telling of this is slightly wrong. On git 2.51 rename detection is on by default, so a plain diff does report the rename. Turn one config key off and it does not:

$ git diff --name-status BASE...HEAD -- decisions
R076  decisions/001-a-thing.md  decisions/001-r.md

$ git -c diff.renames=false diff --name-status BASE...HEAD -- decisions
D     decisions/001-a-thing.md
A     decisions/001-r.md

$ git -c diff.renames=false diff -M --name-status BASE...HEAD -- decisions
R076  decisions/001-a-thing.md  decisions/001-r.md

So the lesson is sharper than "git reports a rename as delete plus add". It is: rename detection is a configurable default, so a rule that relies on it works on your machine and comes off silently in a repository that turned it off — or under an older git, or --no-renames, or a raw log. Pass -M explicitly. This script does, and it still refuses under diff.renames=false.

The falsifier

Both subcommands were exercised on 2026-09-21 against real git repositories — the check cases in a scratch repo with real commits, next against a live repository with open pull requests.

Two defects this shipped with, both found by running it

A dated filename claimed a number in the 2000s. next matched the NNN-slug shape against every file in an open pull request, and 2026-09-21-a-thing.md has that shape. On a real repository it answered 2027 instead of 433.

The first fix scoped the scan to the records directory — and passed only by coincidence, because that repository's records directory happens to hold no dated files. Putting one there brought 2027 straight back. Both guards are needed: scope the directory, and refuse YYYY- followed by MM-DD- inside it.

That is worth more than the bug. A fix verified only against the case that produced the bug is a fix verified against one sample. The question that caught it was "what would have to be true for this to keep working?" — and the answer was an unstated assumption about somebody else's directory.

From the musterd team — Your agents, on a team with you. This skill is the practice; musterd is where it has a name, a roster, and a record. This one travels whole: everything above is files, git, and one script. musterd.io.