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.
- 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.
- One decision, one sentence. The title is the decision in the imperative. If you need
"and", write two ADRs.
- 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).
- 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.
- Decision in active voice ("We will…"), with its scope.
- 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.
- 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 …".
- 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.
- 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.
Done when
- The file is in the repo's ADR directory with the next free number, the date, and a status.
- Context, options (each with its rejection reason), decision and consequences (including
what gets harder and a revisit trigger) are present.
- Links exist from the governed code/doc to the ADR; a superseded ADR's status is updated.
- Formatting passes the repo's markdown check if configured (e.g.
npx --no -- prettier --check).
Review checklist (concrete defects only)
- More than one decision in one record, or a title that is a topic, not a decision.
- An option listed without why it lost; consequences with no downside.
- An accepted ADR's body edited instead of superseded; a reused number.
Accepted status on a decision that needed human sign-off.
- The ADR contradicts an existing ADR or lore decision without superseding it.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While writing the record you make a lasting decision explicit — the options weighed and why one won — which is exactly the knowledge later agents need before they contradict it. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: write-adr3description: Use when a ticket, plan, or delivery involves a decision with lasting consequences — a library choice, a data model, a boundary between services, a protocol, a deliberate trade-off — and it must be recorded as an Architecture Decision Record others can find and challenge. Invoke for "write an ADR", "document why we chose X", when a decision is escalated via request_decision and resolved, or when you find yourself explaining a non-obvious choice in a commit message.4stack: []5area: docs6metadata:7 source: https://skillmd.com/skills/tmj-90/write-adr8---910# Write an Architecture Decision Record1112An ADR records one architecturally significant decision in Michael Nygard's format — Title,13Status, Context, Decision, Consequences — so a future reader can see why, judge whether the14reasons still hold, and supersede it deliberately. Keep it to one or two pages, dated,15numbered, and immutable once accepted.1617## Template1819```markdown20# NNNN. <Imperative decision, e.g. "Use SQLite as the control-plane store">2122Date: YYYY-MM-DD23Status: Proposed | Accepted | Rejected | Deprecated | Superseded by [NNNN](NNNN-slug.md)2425## Context26The forces: requirements, constraints, what hurt, what is uncertain. Facts, not advocacy.2728## Options considered29- **<Option A>** — why it lost, concretely.30- **<Option B>** — why it lost.3132## Decision33We will <do X>. <Scope: where it applies and where it does not.>3435## Consequences36Easier: … Harder: … Now forbidden: … Revisit if: <measurable trigger>.37```3839"Options considered" extends Nygard's format; keep it unless the repo's template40omits it.4142## Procedure4344When you cannot write files (planning and spec roles), do not draft the file: put the45decision and its options in your output instead, as a ticket or acceptance criterion in46a plan or a `decision` clause in a spec, so a delivery ticket writes the ADR.47481. **Find the convention.** Look for `docs/adr/`, `docs/decisions/`, `doc/adr/`,49 `architecture/decisions`, or a numbered `NNNN-title.md` series; match its template,50 numbering, and status vocabulary. If none exists, create51 `docs/adr/0001-record-architecture-decisions.md` (the convention itself) and write yours52 as `0002-…`. Numbers are sequential and never reused. `search_lore` for decisions53 already recorded so you neither duplicate nor silently contradict one.542. **One decision, one sentence.** The title is the decision in the imperative. If you need55 "and", write two ADRs.563. **Context honestly.** Enough that a reader in a year understands why the question arose:57 the requirement, constraint or incident that forced it, with links to the ticket or58 spec. Include the non-functional forces that actually mattered (consistency under59 concurrent writers, durability of acknowledged writes, operability, cost).604. **Options actually weighed**, each with the concrete reason it lost. "Considered61 Postgres; rejected because the factory must run with zero services on a laptop" is62 useful; "considered alternatives" is not. Include "do nothing" when it was viable.635. **Decision in active voice** ("We will…"), with its scope.646. **Consequences — all of them.** What becomes easier, what becomes harder, what is now65 forbidden, new risks and how they are mitigated, and a measurable revisit trigger. This66 is the most valuable section and the most often skipped.677. **Set status truthfully.** An agent-made choice within the ticket's authority may be68 `Accepted` and is flagged with `request_decision` at `log_only`/`agent_can_choose`. A69 product, architecture or security call you cannot make is `Proposed` and escalated with70 `request_decision` as `human_required`; do not mark it accepted yourself. To change an71 accepted decision, write a new ADR that says "Supersedes NNNN" and change only the old72 one's status line to "Superseded by …".738. **Link both ways.** Reference the ADR from where the decision bites (module header74 comment, README section, config file) and from the ADR index if the repo keeps one.759. **Mirror into memory and evidence.** Call `suggest_lore` with kind `decision`76 summarising the choice and reason, citing the ADR path in the body (the `source`77 field takes only a URL). Evidence the file with the `record-evidence` skill, then78 stop.7980## Done when8182- The file is in the repo's ADR directory with the next free number, the date, and a status.83- Context, options (each with its rejection reason), decision and consequences (including84 what gets harder and a revisit trigger) are present.85- Links exist from the governed code/doc to the ADR; a superseded ADR's status is updated.86- Formatting passes the repo's markdown check if configured (e.g. `npx --no -- prettier --check`).8788## Review checklist (concrete defects only)8990- More than one decision in one record, or a title that is a topic, not a decision.91- An option listed without why it lost; consequences with no downside.92- An accepted ADR's body edited instead of superseded; a reused number.93- `Accepted` status on a decision that needed human sign-off.94- The ADR contradicts an existing ADR or lore decision without superseding it.9596## Capture lore9798This skill is one of the places durable, reusable knowledge naturally surfaces:99**While writing the record you make a lasting decision explicit — the options weighed and why one won — which is exactly the knowledge later agents need before they contradict it.** That kind of fact is *lore*. Capture it via the **lore-capture100protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):101call the Memory MCP `suggest_lore` once at the close of your work — reusable102conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.