ADR-skill.md

name	create-adr
description	Use when converting design documents into architectural decision records (ADRs), after completing a feature, or when a significant architectural choice was made and needs to be recorded or updated

Create ADR from Design Document

Overview

Extract architectural decisions from a design document and record them as ADRs. Focus on WHY decisions were made (context, rationale, trade-offs) — not HOW (code, steps, tests).

Core rule: One ADR per decision. A single design doc may yield multiple ADRs.

Process

1. Read the design document

Scan the full document looking for:

• Choices between competing approaches
• Constraints or requirements that shaped the design
• Things explicitly not done and why
• Libraries, patterns, or architectures selected

2. Extract decisions (not implementation)

Capture	Skip
Why this approach over alternatives	Code snippets
Trade-offs and consequences	Step-by-step procedures
Files/modules affected	Test details
What was rejected and why	Deployment instructions
Constraints that drove the choice	Configuration values

3. Check the ADR folder

If ADR/ doesn't exist, create this structure using the templates in the Templates section below:

ADR/
├── overview.md      # Index of all ADRs
├── template.md      # Blank ADR template
└── records/

4. Check for duplicates or superseded ADRs

• Read ADR/overview.md to see existing records
• If this decision updates a prior one, mark the old ADR status as Superseded by ADR-NNN
• If genuinely new, assign the next available number

5. Write the ADR

Copy ADR/template.md, fill it in, and save to ADR/records/NNN_short-title.md (lowercase-with-hyphens).

6. Update the index

Add a row to the table in ADR/overview.md:

| NNN | Short Decision Title | Accepted | YYYY-MM-DD |

Templates

overview.md

# Architecture Decision Records

ADRs capture important architectural decisions along with their context and consequences.

## How to Create a New ADR

1. Copy `template.md`
2. Save as `records/NNN_title.md` (next available number, lowercase-with-hyphens)
3. Fill all sections — focus on WHY, not HOW
4. Add a row to the index below

## ADR Index

| # | Title | Status | Date |
|---|-------|--------|------|

template.md

# [ADR-NNN] Title

**Status:** Accepted

**Date:** YYYY-MM-DD

## Context
Why did this decision need to be made? What problem or constraint prompted it?

## Decision
What was decided, stated plainly.

## Alternatives Considered
- **Option A** — why rejected
- **Option B** — why rejected

## Consequences
+ What becomes easier or better
- What becomes harder, constrained, or is now a known limitation

## Files Affected
- `path/to/relevant/file`

Common Mistakes

• Including code — ADRs age poorly; code changes but decisions don't
• One ADR per doc — Split by decision, not by document
• Omitting alternatives — Future readers need to know what was rejected and why
• Vague consequences — Be specific: "queries now require a join" beats "slightly slower"
• No affected files — Linking decisions to code is critical for traceability