docs/decision-records/

Every decision that shapes the product or the system gets a record here. If a decision has no record it does not exist: reviewers and agents treat undocumented divergence as a red flag, not as somebody's prerogative. This is the folder that answers why is it like this six months after everyone who was in the room has forgotten.

What it is for

Two streams, one question each.

When you cannot tell which, ask who would overrule the decision. When both would, write the BDR and let the ADR reference it.

What goes in here

A contestable, re-litigable trade-off. Someone could reasonably have chosen otherwise, and without the record the argument reopens. That is the whole test.

One file per decision, ADR-NNN-slug.md, three digits, gapless, never reused. A retired record is marked Superseded or Withdrawn, never deleted, because the number stays a permanent anchor and the history of what you believed is the point.

# ADR-014: One authored tree

**Status:** Accepted
**Date:** 2026-07-22

## Context
The tree shipped to adopters and the repo's own working files were the same files.

## Decision
One authored tree under standard/. Repo-own material never lands in it.

## Options considered
1. Two trees, synced by a script. Rejected: the script becomes the truth.
2. One tree with an exclusion list. Rejected: the list drifts, silently.

## Consequences
tree-check gains a leak test. A repo-own file in standard/ fails the build.

## Revisit when
An adopter needs a file we keep repo-own.

That example is the target length, not a simplified version of one. Write the shortest record that still answers why for someone who was not in the room. Length is a cost, not a sign of rigour: a decision that fits in one sentence gets one sentence, and a section with nothing to say gets one line rather than a paragraph of throat-clearing. Comprehensive means every section is answered, not that each answer is long - and a record nobody finishes reading fails at the only job it has. A draft that runs long is usually arguing for the decision rather than recording it.

Revisit when is not decoration. It names the concrete signal that would reopen the decision, which is the difference between a record and an opinion.

Neither is Confirmation, and it belongs to both streams. It names how you would find out the decision is not being kept - a guard, a test, a CI check, a review step, the spec it changed - which is a different question from Revisit when (when to reopen it) and, in a BDR, from How we would know we were wrong (that the call itself was a mistake). A business decision with a technical consequence and no named check is the one that quietly stops being followed; naming where compliance is checked is not designing it, which stays the ADR's job.

What does not go in here

How it behaves. That is the capability spec. A decision record that describes the feature has become a duplicate of the spec, and the two will disagree.

How it is built. That is ARCHITECTURE.md. There is deliberately no TDR stream: "living technical design" is behaviour plus structure, and both already have homes.

A settled way of doing things. If reversing it would cost a search-and-replace it is a convention and belongs in AGENTS.md. If reversing it would cost a rewrite it is a decision. A significant choice usually produces both: the record holds the why, the convention holds the resulting practice.

A maybe. Proposed means a decision awaiting ratification, not an idea somebody likes. Speculation lives in docs/ideas/ and mints no record until it is approved.

The standard's own decisions. An ADR-0NN reference inside a file the standard shipped points at the standard's decisions, not yours. Your repo's records start at ADR-001 and the two numbering lines never meet.

How you actually use it

You do not open the template. You say what happened, while you still remember:

we agreed on Postgres over Mongo yesterday, mainly for the reporting joins - write it up

we need a queue for the export jobs - record the decision first

The agent drafts the record with the options it can find, their trade-offs and a recommendation, and asks only what it cannot work out. You approve; it flips to Accepted.

When an accepted record turns out to be wrong, it is never edited into a new opinion:

ADR-014 says one tree; we are splitting it - supersede it

The new record supersedes the old, and the old keeps its text plus a Superseded by line.

Which wins when two documents disagree

PRINCIPLES.md
  -> ADR / BDR (accepted decisions - why)
    -> specs/<capability> (behavior) + ARCHITECTURE.md (structure)
      -> conventions, agent rules, skills
        -> code

Higher wins. If the code disagrees with an accepted record, that is a stop-and-propose, not a silent divergence. specs/ and ARCHITECTURE.md are peers: one says what the system does, the other how it is put together, and both answer to the decisions above them.

Decisions behind it

• Records are immutable once accepted. Editing one to match a new opinion erases the only evidence that the old one was ever held, which is the single thing the folder exists to keep.
• ADR-010 - nothing is a record until it is approved. Minting an ADR for every idea was the alternative, and it fills a repo with decisions nobody made. Ideas got their own home instead.
• No TDR stream. A third record type for technical design was considered and dropped: everything it would hold is either behaviour (spec) or structure (ARCHITECTURE.md), and a stream with no unique content becomes the place things go to be ignored.
• At most three options per record. More is analysis paralysis wearing a template.

Reference

• Status. Required - part of the core profile.
• How it arrives. fill-from-repo - scaffold the shell from the standard, then author the body from THIS repo's reality - never blind-copy the example prose (ARCHITECTURE, PRODUCT, specs)
• Shipped form. read it in the standard's own tree

The rule that requires it

A contestable, re-litigable choice MUST be recorded as a decision record

See it in the spec

Read this page's markdown, or its source on GitHub.