write-adr

Write an Architecture Decision Record

An ADR records one architecturally significant decision in Michael Nygard's format — Title, Status, Context, Decision, Consequences — so a future reader can see why, judge whether the reasons still hold, and supersede it deliberately. Keep it to one or two pages, dated, numbered, and immutable once accepted.

Template

# NNNN. <Imperative decision, e.g. "Use SQLite as the control-plane store">

Date: YYYY-MM-DD
Status: Proposed | Accepted | Rejected | Deprecated | Superseded by [NNNN](NNNN-slug.md)

## Context
The forces: requirements, constraints, what hurt, what is uncertain. Facts, not advocacy.

## Options considered
- **<Option A>** — why it lost, concretely.
- **<Option B>** — why it lost.

## Decision
We will <do X>. <Scope: where it applies and where it does not.>

## Consequences
Easier: … Harder: … Now forbidden: … Revisit if: <measurable trigger>.

"Options considered" extends Nygard's format; keep it unless the repo's template omits it.

Procedure

When you cannot write files (planning and spec roles), do not draft the file: put the decision and its options in your output instead, as a ticket or acceptance criterion in a plan or a decision clause in a spec, so a delivery ticket writes the ADR.

1. Find the convention. Look for docs/adr/, docs/decisions/, doc/adr/, architecture/decisions, or a numbered NNNN-title.md series; match its template, numbering, and status vocabulary. If none exists, create docs/adr/0001-record-architecture-decisions.md (the convention itself) and write yours as 0002-…. Numbers are sequential and never reused. search_lore for decisions already recorded so you neither duplicate nor silently contradict one.
2. One decision, one sentence. The title is the decision in the imperative. If you need "and", write two ADRs.
3. Context honestly. Enough that a reader in a year understands why the question arose: the requirement, constraint or incident that forced it, with links to the ticket or spec. Include the non-functional forces that actually mattered (consistency under concurrent writers, durability of acknowledged writes, operability, cost).
4. Options actually weighed, each with the concrete reason it lost. "Considered Postgres; rejected because the factory must run with zero services on a laptop" is useful; "considered alternatives" is not. Include "do nothing" when it was viable.
5. Decision in active voice ("We will…"), with its scope.
6. Consequences — all of them. What becomes easier, what becomes harder, what is now forbidden, new risks and how they are mitigated, and a measurable revisit trigger. This is the most valuable section and the most often skipped.
7. Set status truthfully. An agent-made choice within the ticket's authority may be Accepted and is flagged with request_decision at log_only/agent_can_choose. A product, architecture or security call you cannot make is Proposed and escalated with request_decision as human_required; do not mark it accepted yourself. To change an accepted decision, write a new ADR that says "Supersedes NNNN" and change only the old one's status line to "Superseded by …".
8. Link both ways. Reference the ADR from where the decision bites (module header comment, README section, config file) and from the ADR index if the repo keeps one.
9. Mirror into memory and evidence. Call suggest_lore with kind decision summarising the choice and reason, citing the ADR path in the body (the source field takes only a URL). Evidence the file with the record-evidence skill, then stop.