Create ADR
Record one architecture decision — the "why" that code and commit messages
can't carry — as a numbered, immutable file in the target repository.
An ADR records a decision made, not a proposal under discussion. If the
decision isn't settled yet, help settle it in conversation first; write the
ADR after.
Steps
Locate the ADR home. Look for an existing convention in the target
repo: docs/adr/, docs/decisions/, adr/, or an existing NNNN-*.md
series anywhere under docs/. Follow whatever exists (numbering width,
template style). If none exists, create docs/adr/ and start at 0001.
- Completion criterion: directory and next sequence number are known.
Gather the decision. From the conversation (ask only for gaps):
the decision itself, the context/forces that made it necessary, the
alternatives considered, and why they lost. If the decision came out of
work in this session, pull the concrete evidence (files, constraints)
you already have instead of re-asking.
Draft the ADR — in English, as a repository artifact. Template
(skip a section only when genuinely empty, and keep the heading with
"None."):
# NNNN. <Decision title, imperative — "Use X for Y">
Date: YYYY-MM-DD
Status: Accepted
## Context
<the forces: requirements, constraints, problems that made a decision necessary>
## Decision
<what was decided, stated as fact>
## Alternatives considered
<each alternative and the concrete reason it was rejected>
## Consequences
<what becomes easier, what becomes harder, follow-ups now required>
Confirm, then write. Show the draft to the user; on approval write
NNNN-<kebab-slug-of-title>.md into the ADR home. If this ADR supersedes
an earlier one, also edit the old ADR's Status to
Superseded by NNNN — that edit is the one exception to ADR immutability.
- Completion criterion: file written; any superseded ADR's status updated.
Report the file path and suggest committing it with the related change
(docs: add ADR NNNN — <title>).
Failure modes
- The "decision" is still an open question → don't write a
Status: Accepted
ADR for it; either help decide first or, if the user wants the open state
recorded, use Status: Proposed and say so.
- Two decisions in one request → two ADRs; one record per decision.
1---2name: create-adr3description: Record an architecture/design decision as an ADR (Architecture Decision Record) in the target repository's docs/adr/. Use when the user wants to document a design decision, its alternatives and consequences, or says "record this decision" / "write an ADR".4---56# Create ADR78Record one architecture decision — the "why" that code and commit messages9can't carry — as a numbered, immutable file in the target repository.1011An ADR records a **decision made**, not a proposal under discussion. If the12decision isn't settled yet, help settle it in conversation first; write the13ADR after.1415## Steps16171. **Locate the ADR home.** Look for an existing convention in the target18 repo: `docs/adr/`, `docs/decisions/`, `adr/`, or an existing `NNNN-*.md`19 series anywhere under `docs/`. Follow whatever exists (numbering width,20 template style). If none exists, create `docs/adr/` and start at `0001`.21 - Completion criterion: directory and next sequence number are known.22232. **Gather the decision.** From the conversation (ask only for gaps):24 the decision itself, the context/forces that made it necessary, the25 alternatives considered, and why they lost. If the decision came out of26 work in this session, pull the concrete evidence (files, constraints)27 you already have instead of re-asking.28293. **Draft the ADR** — in English, as a repository artifact. Template30 (skip a section only when genuinely empty, and keep the heading with31 "None."):3233 ```markdown34 # NNNN. <Decision title, imperative — "Use X for Y">3536 Date: YYYY-MM-DD37 Status: Accepted3839 ## Context40 <the forces: requirements, constraints, problems that made a decision necessary>4142 ## Decision43 <what was decided, stated as fact>4445 ## Alternatives considered46 <each alternative and the concrete reason it was rejected>4748 ## Consequences49 <what becomes easier, what becomes harder, follow-ups now required>50 ```51524. **Confirm, then write.** Show the draft to the user; on approval write53 `NNNN-<kebab-slug-of-title>.md` into the ADR home. If this ADR supersedes54 an earlier one, also edit the old ADR's `Status` to55 `Superseded by NNNN` — that edit is the one exception to ADR immutability.56 - Completion criterion: file written; any superseded ADR's status updated.57585. **Report** the file path and suggest committing it with the related change59 (`docs: add ADR NNNN — <title>`).6061## Failure modes6263- The "decision" is still an open question → don't write a `Status: Accepted`64 ADR for it; either help decide first or, if the user wants the open state65 recorded, use `Status: Proposed` and say so.66- Two decisions in one request → two ADRs; one record per decision.
atman-33