ADR Writer

---
name: adr-writer
description: Use when writing an Architecture Decision Record. Triggers on "write an ADR", "architecture decision record", "document this decision", or design discussion notes that need to be made durable.
---

# ADR Writer

ADRs exist to make the future engineer's life easier. The good ones answer "why did we choose X over the obvious alternatives?" in 5 minutes. The bad ones are 4-page essays nobody reads.

Aim for 1 page. Two max.

## Required inputs

1. **The decision** — what you chose, in plain language
2. **Context** — what was true about the system / team / constraints when the decision was made
3. **Alternatives considered** — at least 2, ideally 3, with WHY they were rejected
4. **Consequences** — what becomes easier, harder, or risky as a result
5. **Status** — Proposed / Accepted / Superseded / Deprecated

If the user only has the decision and no alternatives, push back: "What were the 2-3 other options? An ADR with no rejected alternatives reads like a marketing pitch."

## Structure (strict — don't deviate)

```
# ADR-NNN: [Short title in active voice — "Use Postgres for billing"]

- **Status**: Accepted
- **Date**: 2026-04-29
- **Deciders**: [names or team]
- **Supersedes**: [ADR-NNN if applicable]

## Context

What forces are at play? What's true about our system, team, traffic, constraints
right now that this decision has to live with? 1-2 paragraphs. No solution yet.

## Decision

We will [do X].
1-2 sentences. Active voice. No hedging.

## Alternatives considered

### Option A: [name]
- Pros: [...]
- Cons: [...]
- Rejected because: [specific reason tied to context above]

### Option B: [name]
- Pros: [...]
- Cons: [...]
- Rejected because: [...]

## Consequences

- **Positive**: what becomes easier
- **Negative**: what becomes harder or what we're locking ourselves into
- **Risks**: what could make this decision wrong; what would trigger revisiting

## References

[Links to design docs, benchmarks, related ADRs, RFCs]
```

## Tone

- Past tense for context, present/future for decision and consequences
- No selling. The ADR isn't a pitch — it's a record. "We chose Postgres because we already operate it" beats "Postgres is a powerful database that..."
- Specific. "Reads scale to ~5K rps; writes ~500 rps" beats "high traffic"
- Honest about downsides. "We accept that DynamoDB would have been operationally cheaper" is more credible than pretending there were no trade-offs.

## Anti-patterns

- The "we chose the obvious thing" ADR with no alternatives — useless
- The ADR that re-litigates the decision in 5 pages — write a design doc separately if needed
- Status forever stuck on "Proposed" — set the status when the decision is made
- Never linking from the code that implements it back to the ADR

## Output

Numbered ADR file (ADR-NNN-short-title.md format). If the user hasn't picked a number, suggest the next one in their repo's `docs/adr/` folder pattern. End with: "Once accepted, link this from any code that depends on this decision (top-of-file comment or README)."