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)

Format: NNNN-kebab-case-title.md Examples:

• 0001-use-postgresql-database.md
• 0002-adopt-event-driven-architecture.md
• 0003-choose-react-for-frontend.md

---

Phase 2: Select Template Variant

Choose the MADR variant based on decision complexity. Load only one reference file.

Complexity	Variant	Reference File	When to Use
High	Full	references/adr/madr-full.md	Multiple options, significant consequences, cross-team impact
Medium	Minimal	references/adr/madr-minimal.md	Clear options, moderate impact, standard decisions
Low	Bare	references/adr/madr-bare.md	Quick capture, decision already made, fill details later

Default: Minimal (covers most decisions). Suggest full if the decision involves multiple teams, has long-term commitment, or the user mentions trade-offs.

If uncertain, ask:

"How detailed should this ADR be? Full (thorough analysis with pros/cons per option), minimal (key context and outcome), or bare (headings only for quick capture)?"

---

Phase 3: Gather Decision Context

Collect the information needed to fill the template:

- What decision was made (or needs to be made)?
- What problem or question prompted this decision?
- Decision drivers (requirements, constraints, team capabilities)
- Options considered (at least 2 for full/minimal)
- Pros and cons of each option
- Consequences — positive, negative, and neutral
- Related ADRs or prior decisions

If recording a past decision:

• Set status to Accepted (it's already decided)
• Note the date or context when it was decided

If recording a pending decision:

• Set status to Proposed
• Flag for team review

---

Phase 4: Generate ADR

Fill the selected template:

FILENAME = {NNNN}-{kebab-case-title}.md
FILL template sections with gathered context
SET status:
  - "Proposed" for pending decisions
  - "Accepted" for retrospective recording

---

Phase 5: Validate

Before writing, check:

[ ] Status field present and valid (Proposed | Accepted | Deprecated | Superseded)
[ ] Context section explains the problem clearly
[ ] Decision drivers documented (for full/minimal)
[ ] At least 2 options considered (for full/minimal)
[ ] Consequences noted (for full/minimal)
[ ] Related ADRs linked if applicable
[ ] Filename matches NNNN-kebab-case-title.md pattern
[ ] No number collision with existing ADRs

---

Phase 6: Write ADR

# Write the ADR file
# Path: ${PROJECT_ROOT}/docs/adr/{NNNN}-{title}.md

Confirm creation with:

• File path
• ADR number and title
• Status
• Summary of the decision

---

Status Lifecycle Management

ADRs follow this lifecycle:

Proposed → Accepted → Deprecated
                   → Superseded by [ADR-NNNN](link)

To update an existing ADR's status:

1. Open the ADR file
2. Change the ## Status section
3. If superseding: add Superseded by [ADR-NNNN](NNNN-title.md) and create the new ADR with a link back

Never delete an ADR. Mark as Deprecated or Superseded instead.

---

Quality Standards

• Sequential number assigned (no gaps, no collisions)
• Status lifecycle followed (valid status value)
• Decision drivers documented (not just the conclusion)
• Options considered with pros/cons (at least 2 for full/minimal)
• Consequences noted (positive and negative)
• Related ADRs linked when applicable
• Filename follows NNNN-kebab-case-title.md convention
• Only one MADR variant loaded per invocation

---

Anti-Patterns

❌ ADR without context

# ADR 0005: Use Redis
We decided to use Redis.

✅ ADR with full decision context

# ADR 0005: Use Redis for Session Storage

## Status
Accepted

## Context and Problem Statement
We need a session store that supports horizontal scaling.
Current in-memory sessions don't survive restarts.

## Decision Drivers
- Must support cluster deployment
- Team has Redis experience
- Need sub-millisecond latency

## Decision Outcome
Chosen: Redis, because it meets all drivers and the team
has operational experience.

---

❌ Missing status

# ADR 0003: Choose React

## Context
We need a frontend framework...
(no status section)

✅ Explicit status lifecycle

## Status
Accepted

(or: Superseded by [ADR-0007](0007-migrate-to-svelte.md))

---

❌ Deleting outdated ADRs

rm docs/adr/0003-choose-angular.md
(history lost)

✅ Superseding with new ADR

# ADR 0003: Choose Angular
## Status
Superseded by [ADR-0007](0007-migrate-to-svelte.md)

---

❌ Single option "decision"

We considered React. We chose React.

✅ Genuine alternatives

Considered: React, Vue, Svelte
Chose React because: team familiarity, ecosystem maturity
Trade-off: larger bundle size than Svelte

---

Exit Signals

Signal	Meaning
"adr created"	Decision recorded, file written
"refine"	Continue iterating on the ADR
"abort"	Cancel ADR creation
"write docs"	→ Redirect to docs:write
"audit docs"	→ Redirect to docs:audit

When complete: "ADR created at docs/adr/NNNN-title.md. Status: {Proposed|Accepted}."