docs-adr

docs:adr — Architecture Decision Records

Philosophy: Decisions are perishable — context fades, people leave, rationale is forgotten. ADRs capture the WHY behind architectural choices when it's fresh. A brief ADR now is worth more than a detailed one never written.

Core Principles

1. Capture when fresh - Record decisions while context is available
2. Context over conclusion - The reasoning matters more than the outcome
3. Sequential and immutable - ADRs are numbered, never deleted (only superseded)
4. Right-sized - Full analysis for big decisions, bare capture for quick ones
5. Status lifecycle - Every ADR has a clear status that evolves

---

Trigger Conditions

Run this skill when:

• Making or recording an architectural decision
• Documenting why a technology or approach was chosen
• Capturing decision context before it's lost
• User says "record this decision", "create an ADR", "document why we chose", "capture rationale"

Do NOT use this skill for:

• Writing general documentation → Use docs:write
• Assessing documentation health → Use docs:audit
• "Write a tutorial" or "generate README" → Use docs:write

---

Critical Sequence

Phase 0: Prerequisites Check

Step 0.1 - Resolve Project Root:

PROJECT_ROOT=$(git rev-parse --show-toplevel)
echo "Project root: ${PROJECT_ROOT}"

# Ensure ADR folder exists
mkdir -p "${PROJECT_ROOT}/docs/adr"

Step 0.2 - Check Existing ADRs:

# List existing ADRs to determine next number
ls "${PROJECT_ROOT}/docs/adr/" | grep -E "^[0-9]{4}-" | sort -r | head -5

# Check for related ADRs
grep -rl "{decision keywords}" "${PROJECT_ROOT}/docs/adr/"*.md 2>/dev/null

Verify:

[ ] PROJECT_ROOT resolved correctly
[ ] docs/adr/ folder exists (created if needed)
[ ] Determined next sequential ADR number
[ ] Checked for related existing ADRs

---

Phase 1: Determine Next Number

Scan existing ADRs and assign the next sequential number:

SCAN docs/adr/ for files matching NNNN-*.md
HIGHEST = maximum NNNN found
NEXT = HIGHEST + 1 (zero-padded to 4 digits)

IF no existing ADRs:
  NEXT = 0001

VERIFY no file exists at docs/adr/{NEXT}-*.md (collision check)