mhylle/claude-skills-collection/adr

Architectural Decision Records (ADR)

<!-- contents: generated by tests/skill_structure.py --write; edit headings, not this block -->

Contents

• Design Principles
• When to Use This Skill
• ADR Location and Naming
• Getting the Next ADR Number
• ADR Status Values
• Creating an ADR
• Workflow
• Integration with Other Skills
• Response Format (for subagent use)
• Listing Existing ADRs
• Searching ADRs
• Deprecating an ADR
• Quality Checklist
• Best Practices
• Resources

Reference files (open one when a step points to it):

• references/adr-template.md: ADR-NNNN: [Title]
• references/index-template.md: Architectural Decision Records

<!-- /contents -->

Document significant architectural and technical decisions in a standardized, searchable format optimized for LLM context efficiency.

Design Principles

Context Conservation

ADRs are designed for efficient LLM consumption:

1. Small, focused files - One decision per ADR, minimal content
2. Quick Reference block - First 5 lines summarize the entire ADR
3. Central INDEX.md - Single file listing all ADRs with one-line summaries

LLM Reading Strategy

When consulting ADRs, follow this tiered approach:

TIER 1: Read INDEX.md (one file, all summaries)
        ↓ Identify potentially relevant ADRs
TIER 2: Read Quick Reference block only (first 10 lines of candidate ADRs)
        ↓ Confirm relevance
TIER 3: Read full ADR content (only when details are needed)

Implementation:

# Tier 1: Scan index
Read("docs/decisions/INDEX.md")
 
# Tier 2: Quick reference only (use limit parameter)
Read("docs/decisions/ADR-0001-title.md", limit=10)
 
# Tier 3: Full content (only if needed)
Read("docs/decisions/ADR-0001-title.md")

When to Use This Skill

Directly invoked when:

• Making a significant technical decision
• Choosing between architectural approaches
• Establishing patterns or conventions
• Documenting why a particular technology was selected

Automatically invoked by other skills when:

• create-plan: Design decision is made in Phase 4
• implement-plan: Mismatch discovered or architectural choice made during implementation
• brainstorm: Key decisions identified during analysis

ADR Location and Naming

Directory: docs/decisions/

Naming Convention: ADR-NNNN-short-title.md

• NNNN: Zero-padded sequential number (0001, 0002, etc.)
• short-title: Lowercase, hyphenated description (max 50 chars)

Examples:

• ADR-0001-use-jwt-for-authentication.md
• ADR-0002-postgresql-over-mongodb.md
• ADR-0003-event-sourcing-for-audit.md

Getting the Next ADR Number

Before creating an ADR, determine the next sequence number:

# Find highest existing ADR number
ls docs/decisions/ADR-*.md 2>/dev/null | sort -t- -k2 -n | tail -1 | grep -oP 'ADR-\K\d+' || echo "0000"

If no ADRs exist, start with 0001.

ADR Status Values

Creating an ADR

Required Information

Gather these inputs (ask user if not provided):

ADR Template

Use this format (also in references/adr-template.md):

# ADR-NNNN: [Title]
 
> **Quick Reference** | Status: [Accepted] | Date: [YYYY-MM-DD]
> **Decision**: [One sentence: what was decided]
> **Context**: [One sentence: why this decision was needed]
> **Alternatives**: [Rejected options, comma-separated]
> **Impact**: [Key areas affected, comma-separated]
 
---
 
## Context
 
[2-3 sentences max. The problem or opportunity being addressed.]
 
## Decision
 
**We will use [chosen option].**
 
[1-2 sentences explaining the decision.]
 
## Alternatives Considered
 
| Option | Pros | Cons | Why Not |
|--------|------|------|---------|
| [Option A] | [Key pro] | [Key con] | [Brief reason] |
| [Option B] | [Key pro] | [Key con] | [Brief reason] |
 
## Consequences
 
-**Positive**: [Key benefit]
-**Negative**: [Key trade-off]
-**Requires**: [What must be done as a result]
 
## Related
 
-[ADR-XXXX](./ADR-XXXX-title.md): [Relationship]

Quick Reference Block (Mandatory)

The first 5 lines after the title form the Quick Reference block. This enables LLMs to assess relevance without reading the full document.

Format (must fit in ~5 lines):

> **Quick Reference** | Status: [Status] | Date: [Date]
> **Decision**: [One sentence summary of what was decided]
> **Context**: [One sentence on why this decision was needed]
> **Alternatives**: [Comma-separated list of rejected options]
> **Impact**: [Comma-separated list of affected areas/components]

Example:

> **Quick Reference** | Status: Accepted | Date: 2024-01-15
> **Decision**: Use JWT tokens for API authentication instead of sessions.
> **Context**: Need stateless auth for horizontal scaling of API servers.
> **Alternatives**: Session cookies, OAuth tokens, API keys
> **Impact**: Auth service, API gateway, client SDKs

Keeping ADRs Small

Target size: 30-50 lines maximum (excluding Quick Reference)

One decision per ADR. If you find yourself documenting multiple decisions, split into separate ADRs:

Use tables over prose - More scannable, less verbose:

## Alternatives Considered
 
| Option | Pros | Cons | Why Not |
|--------|------|------|---------|
| MongoDB | Flexible schema | No ACID | Need transactions |
| MySQL | Mature, fast | Less JSON support | PostgreSQL better fit |

Workflow

Step 1: Detect ADR Trigger

An ADR should be created when:

1. Explicit request: User asks to document a decision
2. Design choice: During planning, a significant choice between approaches is made
3. Pattern establishment: A new convention or pattern is being introduced
4. Technology selection: A library, framework, or service is chosen
5. Architecture change: Structural changes to the system
6. Deviation from plan: Implementation differs from original plan for good reason

Step 2: Gather Information

If invoked automatically by another skill, extract:

• Context from the current discussion
• Options that were considered
• The decision that was made
• Rationale from the analysis

If information is incomplete, ask the user:

To document this architectural decision, I need:
1. What problem or context led to this decision?
2. What options were considered?
3. Why was this option chosen over others?
4. What are the expected consequences?

Step 3: Create ADR File

1. Determine next ADR number
2. Generate filename from title
3. Write ADR using template
4. Report creation to calling context

Step 4: Update INDEX.md (Required)

Always update `docs/decisions/INDEX.md` when creating, modifying, or deprecating an ADR.

INDEX.md Structure

# Architectural Decision Records
 
Quick reference index for all architectural decisions. Read this file first to identify relevant ADRs.
 
## Active Decisions
 
| ADR | Decision | Impact | Date |
|-----|----------|--------|------|
| [0001](./ADR-0001-use-jwt-auth.md) | Use JWT for API authentication | Auth, API | 2024-01-15 |
| [0002](./ADR-0002-postgresql-database.md) | PostgreSQL as primary database | Data layer | 2024-01-16 |
| [0003](./ADR-0003-redis-caching.md) | Redis for session and query caching | Performance | 2024-01-17 |
 
## Superseded Decisions
 
| ADR | Was | Replaced By | Date |
|-----|-----|-------------|------|
| [0000](./ADR-0000-example.md) | Session-based auth | ADR-0001 | 2024-01-10 |
 
## By Category
 
### Authentication & Security
-[ADR-0001](./ADR-0001-use-jwt-auth.md): JWT for API authentication
 
### Data & Storage
-[ADR-0002](./ADR-0002-postgresql-database.md): PostgreSQL as primary database
-[ADR-0003](./ADR-0003-redis-caching.md): Redis for caching
 
### API Design
(none yet)
 
### Infrastructure
(none yet)

Updating INDEX.md

When adding a new ADR:

1. Add row to "Active Decisions" table
2. Add entry under appropriate category (create category if needed)

When deprecating an ADR:

1. Move row from "Active Decisions" to "Superseded Decisions"
2. Add "Replaced By" reference
3. Update category listing

Creating INDEX.md

If docs/decisions/INDEX.md doesn't exist, create it:

mkdir -p docs/decisions

Then write the initial structure with the first ADR entry.

Integration with Other Skills

From create-plan

When create-plan makes a design decision in Phase 4, it should invoke this skill:

TRIGGER: Design option selected in create-plan Phase 4
ACTION: Create ADR documenting the decision
LINK: Reference ADR in plan's "Design Decision" section

The plan should include:

## Design Decision
 
[Brief description]
 
See [ADR-NNNN](../decisions/ADR-NNNN-title.md) for full rationale.

From implement-plan

When implement-plan encounters an architectural choice:

TRIGGER:
- Mismatch between plan and reality requiring decision
- New pattern being established
- Technology choice during implementation
 
ACTION: Create ADR documenting the decision
LINK: Note in plan file and inline status

From brainstorm

When brainstorm identifies key decisions:

TRIGGER: Analysis identifies significant decisions that should be documented
ACTION: Create ADRs for each major decision (can be "Proposed" status)
LINK: Reference in brainstorm output's "Key Decisions" section

Response Format (for subagent use)

When this skill is invoked by another skill (as a subagent), return concise output:

STATUS: CREATED
ADR: docs/decisions/ADR-NNNN-title.md
INDEX: docs/decisions/INDEX.md (updated)
DECISION: [One-line summary of decision]
IMPACT: [Comma-separated affected areas]

Always confirm INDEX.md was updated - this is critical for LLM discoverability.

Listing Existing ADRs

To review existing decisions:

# List all ADRs with status
grep -l "Status.*Accepted" docs/decisions/ADR-*.md | while read f; do
  title=$(head -1 "$f" | sed 's/# //')
  echo "$f: $title"
done

Searching ADRs

Find ADRs related to a topic:

# Search ADR content
grep -l "authentication" docs/decisions/ADR-*.md

Deprecating an ADR

When a decision is superseded:

1. Update old ADR status: **Status**: Superseded by [ADR-NNNN](./ADR-NNNN-title.md)
2. Create new ADR referencing the old one in "Related Decisions"
3. Update any plans or docs referencing the old ADR

Quality Checklist

Before finalizing an ADR:

Structure (Context Conservation):

• [ ] Quick Reference block is complete (all 5 lines)
• [ ] Quick Reference fits in first 10 lines of file
• [ ] Total ADR is under 50 lines
• [ ] One decision per ADR (no bundled decisions)
• [ ] Uses tables instead of verbose prose