When to Write an ADR

• You are choosing between two or more viable technical approaches.
• The decision will be hard or costly to reverse later.
• A new cross-cutting concern is introduced (auth, observability, data storage).
• A breaking change to a public API or agent contract is planned.

Small, local choices do not need an ADR. Use inline comments or PR descriptions instead.

ADR Template

# ADR-NNNN: <short title>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Superseded by ADR-XXXX | Deprecated

## Context
What forces, constraints, or requirements led to this decision?
One paragraph; no solution yet.

## Decision
What we decided. Be direct. "We will use X because Y."

## Consequences
- **Positive:** what becomes easier or possible.
- **Negative:** what becomes harder or is lost.
- **Neutral:** other notable side-effects.

## Alternatives Considered
Brief notes on approaches that were rejected and why.

File location: docs/adr/NNNN-kebab-title.md

Process

1. Open a GitHub issue tagged adr to socialize the idea.
2. Create a PR adding the ADR file with status Proposed.
3. Gather feedback; revise in-place on the same branch.
4. Change status to Accepted and merge once two maintainers approve.
5. When superseded, update the old ADR's status line — never delete the file.

Existing ADRs