adr

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 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