Skill: ADR Create

What This Skill Does

Documents a technical decision as it happens using the ADR (Architecture Decision Record) format. While retrospective reconstructs past decisions from git history (inferring context), this skill captures the full decision context in real-time — including alternatives considered, trade-offs evaluated, and expected consequences.

When to Use

• When making a significant technical decision (new dependency, architecture change, pattern choice)
• When the user says "let's document this decision" or "why did we choose X?"
• Before implementing a controversial or non-obvious approach
• When create-plan involves architectural choices that should be recorded

Execution Model

• Always: the primary agent runs this skill directly.
• Output: docs/adrs/ADR-NNN-<title>.md

Workflow

Step 1: Identify the Decision

Use the question tool to clarify:

1. What is the decision? (one sentence)
2. What triggered it? (new requirement, problem, tech debt)
3. What alternatives were considered?
4. What was chosen and why?

Step 2: Gather Context

Collect context from the project:

• Related code or modules affected
• Existing patterns that influenced the decision
• Constraints (performance, compatibility, team skills)
• Reference materials (docs, benchmarks, discussions)

Step 3: Determine ADR Number

# Find the next ADR number
ls docs/adrs/ 2>/dev/null | grep -o 'ADR-[0-9]*' | sort -t- -k2 -n | tail -1

If no docs/adrs/ directory exists, create it and start with ADR-001.

Step 4: Write the ADR

Create docs/adrs/ADR-NNN-<slug>.md:

# ADR-NNN: <Title>

## Status

Accepted | Proposed | Superseded by ADR-NNN

## Date

YYYY-MM-DD

## Context

<What is the issue? What forces are at play? What constraints exist?>

## Decision

<What is the change that we're proposing and/or doing?>

## Alternatives Considered

### Alternative A: <name>
- **Pros**: ...
- **Cons**: ...
- **Why rejected**: ...

### Alternative B: <name>
- **Pros**: ...
- **Cons**: ...
- **Why rejected**: ...

## Consequences

### Positive
- <expected benefit>

### Negative
- <expected downside or trade-off>

### Risks
- <what could go wrong>

## References

- <related ADRs, docs, URLs>

Step 5: Cross-Reference

• If this ADR supersedes a previous one, update the old ADR's status
• If this ADR relates to a plan, add a reference in the plan's changelog
• If this affects module documentation, note it for update-docs

Rules

1. Capture the WHY: the most valuable part of an ADR is why the decision was made and why alternatives were rejected. Implementation details belong in docs, not ADRs.
2. Alternatives are mandatory: an ADR without alternatives considered is just a statement, not a decision record. Always document at least one alternative.
3. Consequences are honest: list both positive and negative consequences. Every decision has trade-offs.
4. Keep it concise: an ADR should be 1-2 pages. It's a record, not an essay.
5. Immutable once accepted: accepted ADRs are not edited. If a decision changes, create a new ADR that supersedes the old one.
6. No built-in explore agent: do NOT use the built-in explore subagent type.