01.06

Decision records (ADRs)

Remember why we chose something so we don't relitigate it every six months.

Updated: Oct 3, 2026

On this page

Purpose

Remember why we chose something so we don't relitigate it every six months.

The standard

Write an ADR when a decision is hard to reverse, affects more than one tool, or cost more than a day of debate.
ADRs live in [TEAM: decisions repo or docs/adr/ in the affected repo], numbered ADR-0001-title.md. The index is mirrored at 02.06.
ADRs are immutable once accepted. Change your mind → write a new ADR that supersedes it.

Template

# ADR-00NN: Title
Date · Status (proposed / accepted / superseded by ADR-00MM)
## Context — what forced the decision
## Options considered — 2–4, with trade-offs
## Decision — one paragraph
## Consequences — what gets easier, what gets harder

Procedure

Draft as a PR; reviewers comment; merge = accepted. Link the ADR from the intake issue and the affected repo README.

Owner: Matt · Last reviewed: 2026-09