adr

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 effect
• Proposed — under discussion, not yet finalised
• Deprecated — no longer relevant but not replaced
• Superseded by [NNNN](NNNN-<title>.md) — replaced by a later ADR; also update the superseding ADR to note Supersedes [NNNN]

What belongs here:

• The reasoning and alternatives considered (with reasons each was rejected)
• Constraints that shaped the choice (team size, existing tooling, latency requirements, etc.)
• Known trade-offs being accepted

What does not belong here:

• Implementation steps or how-to instructions
• Code snippets (unless a tiny illustrative example)
• Anything derivable from reading the code

7. Present the draft for approval

Show the full ADR text and ask for approval or changes before writing. This is a permanent record — it should be accurate.

8. Write the file

Use the Write tool to create the file with the approved content.

9. Report back

Tell the user the file path. Offer to stage and commit the file so the decision is captured in git history alongside the code it relates to.