Writing ADRs

ADRs live in docs/adr/ and use sequential numbering: 0001-slug.md, 0002-slug.md, etc.

Create the docs/adr/ directory lazily — only when the first ADR is needed.

Template

# {Short title of the decision}

{1-3 sentences: what's the context, what did we decide, and why.}

That's it. An ADR can be a single paragraph. The value is in recording that a decision was made and why — not in filling out sections.

Written and checked with the writing-prose skill if available, surface markdown. Hard limit: precision and understandability must not suffer.

Optional sections

Only include these when they add genuine value. Most ADRs won't need them.

Status frontmatter (proposed | accepted | deprecated | superseded by ADR-NNNN) — useful when decisions are revisited
Considered Options — only when the rejected alternatives are worth remembering
Consequences — only when non-obvious downstream effects need to be called out

Numbering

Scan docs/adr/ for the highest existing number and increment by one.

Grilling gate

ADRs record load-bearing decisions. Decision made in-conversation, never grilled (docs/glossary/grilling-session.md) → ask user: "Decision wasn't grilled — record as-is?" Proceed only on explicit confirmation. Transcribing decision user already stated explicitly → gate doesn't apply.

When to write an ADR

All three of these must be true:

Hard to reverse — the cost of changing your mind later is meaningful
Surprising without context — a future reader will look at the code and wonder "why on earth did they do it this way?"
The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."

What qualifies

Architectural shape. "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
Integration patterns between contexts. "Ordering and Billing communicate via domain events, not synchronous HTTP."
Technology choices that carry lock-in. Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
Boundary and scope decisions. "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
Deliberate deviations from the obvious path. "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
Constraints not visible in the code. "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
Rejected alternatives when the rejection is non-obvious. If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

writing-adrs