# ADR-NNNN: <one-line title in present tense>

- **Status:** Proposed | Accepted | Superseded by ADR-NNNN | Deprecated
- **Date:** YYYY-MM-DD
- **Deciders:** <names or roles>
- **Related:** ADR-NNNN, RFC-NNNN, `docs/specs/<thing>/spec.md`

## Context

What is going on? What forces are at play? Describe the situation that
prompted the decision in 2–5 paragraphs. Include constraints, prior art,
and what we tried that didn't work — not just the happy path.

ADRs are written for someone reading the codebase a year from now who is
wondering "why on earth did they do it this way?" Answer that question.

## Decision

What did we decide? State it in one or two declarative sentences.

> **We will <do X>.**

Then expand: scope, mechanics, what it covers and what it doesn't. If the
decision involves multiple sub-choices, enumerate them.

## Consequences

The honest accounting.

### Positive

- What gets easier?
- What classes of bugs go away?
- What does the user feel?

### Negative

- What gets harder?
- What new failure modes appear?
- What did we trade away?

### Neutral / monitor

- What remains uncertain and should be reviewed if circumstances change?
- What metric or eval would tell us this decision needs revisiting?

## Alternatives considered

Each alternative gets one paragraph: what it was, why it lost. Don't
straw-man — the alternatives lost on real grounds, name them.

### Alt 1: <name>

…

### Alt 2: <name>

…

## References

- Source material, blog posts, code in other repos
- Conversations with stakeholders (link to RFC or issue)
- Specs or plans that depend on this decision
