Decision records
Decision records are memory for maintainers, not a publishing format.
Repository ADRs explain why a structural decision was made. Brand documentation explains the current rule a reader should follow.
Rule#
Write an ADR for durable decisions that change structure, ownership, quality, privacy, DNS, deployment, or technical boundaries. Publish derived guidance only where the reader needs the current rule.
Use an ADR for#
- documentation structure
- cross-site ownership boundaries
- DNS and Cloudflare configuration boundaries
- quality models and test strategy
- privacy and third-party runtime boundaries
- source-of-truth decisions
- decisions that are likely to be questioned later
Do not use an ADR for#
- ordinary content edits
- copy changes
- page-level navigation tweaks
- implementation details that are already obvious in code
- temporary work notes
Derive, do not duplicate#
When an ADR affects public guidance, rewrite it into the right page:
- the rule goes in Site governance
- the mechanism goes in Site implementation
- visual constraints go in Foundations
- brand recognition goes in Identity
The public page may quietly mention an ADR as a decision source, but it should still read as guidance.
Status#
Accepted ADRs remain valid until another ADR replaces or supersedes them. Do not edit old ADRs to make history look cleaner; add a new decision when the decision changes.