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: . 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?