write-an-adr

---
name: write-an-adr
description: Write an Architectural Decision Record (ADR) to document a significant design choice. Use when user asks to write/create/document an ADR, or to record an architectural decision.
---

# Write an Architectural Decision Record (ADR)

An ADR captures a single architecturally significant decision and its rationale. ADRs are stored in the `adr/` directory at the repo root, numbered sequentially.

## Background

This workflow follows the Nygard ADR format (Status, Context, Decision, Consequences) with practical additions (Date, Rationale, Considered Options) drawn from MADR and the project's existing conventions. See:

- [Nygard's original post](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
- [MADR](https://adr.github.io/madr/)
- [adr.github.io](https://adr.github.io/)

## Prerequisites

- The user describes a decision that has been made (or is being proposed)
- If the user hasn't described the decision clearly, ask clarifying questions before writing

## Steps

1. **Determine the next ADR number**:
   - List files in `adr/` and find the highest existing number
   - Increment by 1, zero-padded to 4 digits (e.g., `0002`)

2. **Gather information from the user**:
   - What problem or issue motivated this decision?
   - What was decided?
   - What alternatives were considered (if any)?
   - What are the expected consequences (positive, negative, neutral)?
   - What is the current status? (default: `Proposed`)
   - If the user has already provided this information (e.g., in a design doc, PR discussion, or prior conversation), extract it rather than asking again

3. **Write the ADR** at `adr/NNNN-<slug>.md` using the template below. The slug should be a short kebab-case summary of the decision (e.g., `use-huggingface-for-assets`).

4. **Review with the user**: Show them the file path and ask if they'd like any changes before considering it done.

## Template

The ADR must use the structure in `assets/adr-template.md`. Copy that file as the starting point, then fill in the placeholders. All sections are required unless marked optional. Write in plain, direct language — avoid jargon and filler.

### Placeholder guidance

| Placeholder | What to write |
| ----------- | ------------- |
| `{TITLE}` | A short noun phrase describing the decision (e.g., "Use HuggingFace Hub for Asset Hosting"). |
| `{STATUS}` | One of: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded`. Default to `Proposed`. If superseded, add a line: `Superseded by [ADR-NNNN](NNNN-slug.md)`. If this supersedes another, add: `Supersedes [ADR-NNNN](NNNN-slug.md)`. |
| `{DATE}` | `YYYY-MM-DD` — the date the decision was made or proposed. Use today's date unless the user specifies otherwise. |
| `{CONTEXT}` | The problem or situation motivating this decision. Describe forces at play — technical constraints, business requirements, team preferences, prior art. Reference issues, PRs, or prior ADRs. Should be understandable by someone unfamiliar with the history. |
| `{OPTION_A/B}` | If multiple approaches were evaluated, list them with pros/cons. Optional for straightforward decisions, recommended when the choice was non-obvious. |
| `{DECISION}` | The change being made. State clearly and concisely. Use active voice ("We will...", "Each eval will..."). Include enough detail to understand the change without reading the full implementation. |
| Consequences | **Positive**: what becomes easier, better, or more reliable. **Negative**: what becomes harder or more complex. **Neutral** (optional): side effects that are neither clearly positive nor negative. |
| `{RATIONALE}` | Optional. If the reasoning isn't fully captured by Context + Consequences, explain *why* this option was chosen. Especially useful when the decision is surprising or counterintuitive. |

## Guidelines

- **One decision per ADR.** If a design doc contains multiple decisions, write separate ADRs for each.
- **Keep it short.** A good ADR is 1-2 pages. If Context is getting long, link to a design doc instead of duplicating it.
- **Write for future readers.** Someone joining the team in 6 months should understand why this decision was made.
- **Immutable once accepted.** Don't edit accepted ADRs to reflect new information. Instead, write a new ADR that supersedes the old one.
- **Status lifecycle:** Proposed → Accepted (or Rejected). Later: Deprecated or Superseded.
- **Link liberally.** Reference PRs, issues, design docs, and other ADRs.
- **Use today's date** unless the user specifies a different date for the decision.

## Notes

- The `Considered Options` and `Rationale` sections are optional but encouraged for non-trivial decisions
- The `Neutral` subsection under Consequences is optional
- If the user provides a design doc or PR discussion as input, extract the decision and context from it rather than asking the user to repeat themselves
- Do not stage or commit the ADR without asking the user first