Prototype a denser decision-record format - #33
Draft
ChrisonSimtian wants to merge 1 commit into
Draft
Conversation
Adds docs/decisions.yaml, covering all ten existing ADRs in 229 lines against their 1,552. Nothing reads it. The ADRs stay authoritative until this is accepted or rejected. The format keeps the two things an ADR is actually needed for — the decision and the alternatives that were rejected, each with the reason it lost — and drops the narrative. It is keyed on a slug rather than a number, because the numbers have already collided twice (two 0001s, two 0002s) and a slug cannot. The legacy number is kept as a field so existing "ADR-0008" references still resolve. Two fields exist to answer questions the current set answers badly. `applies` marks whether a decision is load-bearing now, North Star, or dead, which today takes reading four documents to work out. `relations` records amends, supersedes and conflicts as data rather than as prose scattered through Status paragraphs. The header records where the format does not work: the design-track ADRs are long because their value is the worked API design, not the verdict, and compressing them loses the point. Their entries are deliberately thin. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/decisions.yamlas a candidate replacement fordocs/adr/*.md. Nothing reads it. The ADRs stay authoritative until this is accepted or rejected.Stacked on #32, which is stacked on Fallout-build#637. Review those first.
The case, in numbers
All ten ADRs, in 229 lines against their 1,552 — a 7× reduction.
docs/adr/*.md(excl. README)docs/decisions.yamlThe set has also decayed structurally: two ADR-0001s, two ADR-0002s, and no 0005, 0006, 0009 or 0011. Working out the current release model means reading ADR-0004, then its 2026-05-30 amendment, then its 2026-07-13 amendment, then ADR-0007, then ADR-0008 (which supersedes §2 but preserves §1 and §3–6), then ADR-0012 (which defers §1). That is the problem, not the prose style.
Three design choices worth arguing about
adr:field so existingADR-0008references in code comments, PRs and docs still resolve.applies: now | north-star | never. Answers "is this load-bearing today" as data. Right now that takes reading four documents. Six of ten decisions are load-bearing.relationsas data, not prose.amends,supersedes,conflicts_withbecome fields instead of sentences buried in Status paragraphs. The ADR-0008 / GitFlow collision that Separate current state from North Star across the release and versioning docs Fallout-build/Fallout#637 flagged in a callout is expressible asconflicts_with.Each entry keeps the decision, the forcing reason, and every rejected alternative with the reason it lost. Those are the parts that are expensive to rediscover — the rest is recoverable from git.
Where it does not work
Recorded in the file header rather than glossed over. The design-track ADRs —
cd-primitivesat 440 lines,variables-and-substitutionat 259 — are long because their value is the worked API design and the code samples, not the verdict. Compressing them to a decision line loses the point, and their entries here are deliberately thin. Byadr/README.md's own rule ("Living docs go elsewhere indocs/") those are arguably living design docs filed in the wrong place, which is a separate question this PR does not try to settle.So the honest scope is: this format replaces the process and policy records, not the design ones.
Verification
Parses as YAML; all ten ids unique; legacy ADR numbers preserved and duplicates no longer collide. Content was extracted from each ADR's own Status, Decision and Alternatives-considered sections rather than paraphrased from memory.
If you hate it
Delete one file and one callout. Nothing depends on it.