| disable-model-invocation | true |
| name | adr |
| description | Capture an Architecture Decision Record (ADR) for a significant decision made in the current project. Store in the project's adrs/ folder. Use when the user asks to record a decision, log an ADR, or capture why something was built a certain way. PROACTIVELY suggest capturing an ADR whenever a non-obvious architectural choice is made — technology selection, structural trade-offs, rejected alternatives — especially after a discussion where context and reasoning were developed. A good prompt — "Want me to capture this as an ADR?" |
ADR Skill
Captures a decision as an Architecture Decision Record in the project's ADR directory. ADRs record the why — context, the decision made, alternatives rejected, and consequences — not implementation details.
1. Resolve the project root and ADR directory
The project root is the working directory. Check for an existing ADR directory before creating one:
ls -d adrs/ docs/adr/ docs/decisions/ architecture/decisions/ 2>/dev/null | head -1
Use whichever exists. If none exist, default to adrs/ and create it:
mkdir -p adrs
2. Check for existing ADR format
If ADR files exist, read the most recent one to match its format and section naming exactly. Don't impose a different structure on a project that already has a convention.
3. Confirm the title and framing before drafting
Before writing a full ADR, confirm with the user in one sentence:
"I'll capture this as: '' — decision: <one-line summary>. Does that framing look right?"
This avoids a full redraft if the angle is wrong.
4. Determine the next ADR number
ls adrs/[0-9]*.md 2>/dev/null | sort | tail -1
Parse the numeric prefix from the last file (e.g. 0003 from 0003-use-sqlite.md). Increment by one. If no files exist, start at 0001.
5. Derive the filename
Use the decision title in lowercase kebab-case:
adrs/<NNNN>-<kebab-title>.md
Example: adrs/0004-store-adrs-in-top-level-folder.md
6. Write the ADR
Use this template — keep each section concise (a few sentences to a short paragraph):
# <NNNN>. <Title>
Date: <YYYY-MM-DD>
Status: <Accepted | Proposed | Deprecated | Superseded by [NNNN](<link>)>
## Context
What situation, constraint, or requirement forced this decision? What was the problem space?
## Decision
What was chosen and why? State it directly.
## Alternatives Considered
What else was evaluated and why was it not chosen? This is the most important section for future readers — capture each rejected option and the specific reason it lost.
## Consequences
What gets easier? What gets harder? What is accepted as a trade-off?
Status values:
Accepted — decision is in effectProposed — under discussion, not yet finalisedDeprecated — no longer relevant but not replacedSuperseded by [NNNN](NNNN-<title>.md) — replaced by a later ADR; also update the superseding ADR to note
