Writing Adrs

Writing ADRs

Overview

An ADR records exactly one decision. Problem docs explore; ADRs decide. docs/architecture.md and problem docs are the current state (mutable). ADRs are point-in-time records that can receive minor annotations but should not be substantially rewritten.

ADRs are point-in-time records, not evolving documents

An ADR captures a decision and the context that existed when it was made. It is not a living design document -- that role belongs to docs/architecture.md.

That said, accepted ADRs are not 100% frozen. Minor annotations after the fact are welcome and encouraged:

Acceptable modifications to an accepted ADR:

• Changing its status (e.g., from Accepted to Deprecated or Superseded)
• Adding cross-reference links to related or superseding ADRs
• Adding short notes that connect the ADR to newer decisions or clarifications
• Fixing typos, broken links, or formatting

These annotations keep ADRs useful as navigational aids rather than dead-end documents. When a reader lands on an older ADR, links to subsequent decisions help them find the current state of thinking.

Not acceptable -- write a new ADR instead:

• Substantially rewriting Context to reflect updated understanding
• Editing the Decision to match a revised approach
• Modifying Consequences based on what actually happened
• Turning the ADR into a running log of how the decision evolved

If a decision turned out to be wrong, that is what supersession is for. The original ADR remains as a historical record of what was decided and why. For ongoing design narrative, use docs/architecture.md.

docs/architecture.md is always current

Unlike ADRs, docs/architecture.md is a living document. It must always reflect the current state of architectural decisions. When a new ADR is accepted (or when an ADR supersedes an older one), docs/architecture.md must be updated to reflect the latest decision. It is the single place a reader can go to understand what is true now, without tracing a chain of ADRs.

When to Use

• A specific decision has emerged from discussion in a problem doc
• You need to frame an upcoming decision
• An ADR has been accepted and living documents need updating

Do NOT use for open-ended exploration -- that belongs in problem docs.

The Rules

One decision per ADR

Each ADR decides a single thing. If you find yourself writing "Additionally, we decide..." or "We also require...", stop. That is a second ADR.

Be concise

• Context: 1-3 short paragraphs. Link to problem docs for background instead of restating them.
• Decision: State the decision directly. A few paragraphs at most.
• Consequences: 3-5 bullet points. Each one sentence.

Link, don't repeat

Problem docs exist. Architecture.md exists. Reference them:

# Good
The threat model establishes least-privilege as a cross-cutting principle
(see [security-threat-model.md](../problems/security-threat-model.md)).

# Bad
[3 paragraphs restating the threat model's least-privilege section]

Cross-reference other ADRs

If this decision builds on or relates to another ADR, say so in Context.

Normative specs (docs/normative/)

• Use when the decision needs byte-level or field-level contracts, JSON Schema (or equivalent), canonical YAML or snapshots, or compatibility / conformance artifacts aimed at multiple implementations or automated checks.
• Do not use for open-ended trade-off exploration (that stays in problem docs), for a single architectural choice with no large artifact (keep that in the ADR only), or for duplicating ADR 0003-style repository convention without a versioned contract (do not invent a normative subtree for that).
• Relationship: the ADR states the decision, high-level versioning expectations, and links to docs/normative/<topic>/v<major>/...; the normative folder holds the detailed, versioned contract (v1, v2, …).

Checklist

Follow these steps in order:

1. Find the next number. List docs/ADRs/ on current main, then scan open pull requests for new docs/ADRs/NNNN-*.md files so you do not collide with in-flight ADRs. Pick the lowest unused four-digit NNNN.
2. Read the template. Use docs/ADRs/0000-adr-template.md exactly.
3. Fill in frontmatter. relates_to must reference existing filenames (without .md) from docs/problems/. Use "*" only for ADRs that truly apply to all problem areas. The status in frontmatter must match the ## Status heading in the body (the linter enforces this). The number in the title field and the # heading must have no leading zeros (e.g., "1. Use ADRs", not "0001. Use ADRs"). The four-digit zero-padded format is only for filenames.
4. Choose the right status. Use Accepted when the decision is made. Use Deprecated or Superseded when retiring an ADR. Include an Options section only when there are genuine alternatives worth documenting; if the decision is obvious, just decide it.
5. Write the ADR. Follow the conciseness rules above.
6. Run linters. Stage your changes, then execute make lint and fix any errors before committing.
7. If status is Accepted, update living documents (see below).