ADR Writer

Produce focused ADRs that capture the WHY behind a technical choice.

When to write an ADR

• Picking between two or more real alternatives (DB engine, queue tech, framework, deployment model).
• Reversing a previous decision.
• A choice that's expensive to reverse later (data shape, public API, auth model).
• Anything you've had to re-explain to a teammate more than once.

When NOT to write one

• Trivial choices (variable name, file layout).
• Bug fixes — those go in the commit message and the issue.
• Decisions already documented elsewhere (PRD, design doc).

Template

# ADR <NNNN>: <Short title — what is being decided>

- Status: <proposed | accepted | superseded by ADR-<MMMM> | deprecated>
- Date: <YYYY-MM-DD>
- Deciders: <names>

## Context

What is the problem we're solving? What forces are at play (technical, organizational, time)? Keep this to 2-4 paragraphs. Anyone reading this in a year should understand the situation without needing to ask.

## Decision

We will <do X>.

State it once, clearly. Use active voice. No hedging.

## Alternatives considered

### Option A — <name>
- Pros: ...
- Cons: ...
- Why not chosen: <one sentence>

### Option B — <name>
- Pros: ...
- Cons: ...
- Why not chosen: <one sentence>

(List 2-4 real alternatives. "Doing nothing" is often a valid one.)

## Consequences

### Positive
- <Specific outcome we expect>

### Negative
- <Specific cost or constraint we're accepting>

### Neutral
- <Things that change but aren't obviously good or bad>

Numbering

ADRs are numbered sequentially. Find the next number with:

ls docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1

Then increment. If no docs/adr/ exists yet, propose creating it and start with 0001.

Filename convention

docs/adr/NNNN-short-title-with-hyphens.md — e.g. docs/adr/0007-use-postgres-not-mysql.md.

Style rules

• One decision per ADR. If you're tempted to combine two, write two ADRs.
• "Context" must include the constraints. A reader 2 years later won't remember why time pressure mattered.
• "Alternatives considered" must be real alternatives someone actually proposed — not strawmen.
• "Consequences" must include the negatives. An ADR with only upside is suspect.
• Status tracks the lifecycle. When superseding, link both ways.

Anti-patterns

• Skipping "Alternatives considered" because it was "obvious" — it wasn't obvious to whoever proposed Option B.
• Writing the ADR after the implementation. ADRs are for the decision, not the result.
• Long ADRs. >2 pages means you're writing a design doc — split.