adr

name	adr
description	Document architectural decisions in standardized ADR format. This skill should be used when making significant technical decisions, choosing between approaches, establishing patterns, or when other skills (create-plan, implement-plan, brainstorm) identify decisions that need documentation. Triggers on "document decision", "create ADR", "architectural decision", or automatically when invoked by other skills during planning and implementation.
argument-hint	[decision-title?]

Architectural Decision Records (ADR)

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

Status	Meaning
Proposed	Under consideration, not yet decided
Accepted	Decision made, ready for implementation
Deprecated	Was accepted, now superseded
Superseded	Replaced by another ADR (link to replacement)

Creating an ADR

Required Information

Gather these inputs (ask user if not provided):

Field	Description	Required
Title	Short, descriptive title	Yes
Context	Why is this decision needed?	Yes
Options	What alternatives were considered?	Yes
Decision	What was decided?	Yes
Rationale	Why this option?	Yes
Consequences	What are the implications?	Yes
Related ADRs	Links to related decisions	If applicable

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:

Instead of	Create
"Database and caching choices"	ADR-0001: PostgreSQL for primary database
	ADR-0002: Redis for session caching
"Authentication architecture"	ADR-0003: JWT for API auth
	ADR-0004: OAuth2 for third-party integration

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

Content:

• Decision is clearly stated in one sentence
• Context is 2-3 sentences max
• At least 2 alternatives listed with pros/cons
• Consequences include positive AND negative

Index:

• INDEX.md updated with new entry
• Category section updated
• Impact areas listed accurately

Best Practices

Writing Concise ADRs

1. One sentence, one decision: If you can't state the decision in one sentence, you may be bundling multiple decisions
2. Tables over paragraphs: Alternatives table is more scannable than prose
3. Impact over rationale: Focus on what's affected, not lengthy justification
4. Quick Reference is the ADR: If someone only reads the Quick Reference, they should understand the decision

Size Guidelines

Section	Target Length
Quick Reference	5 lines (mandatory)
Context	2-3 sentences
Decision	1-2 sentences
Alternatives table	2-4 rows
Consequences	3 bullets
Total ADR	30-50 lines

When to Split ADRs

Split into multiple ADRs when:

• Decision covers multiple technologies
• Decision affects unrelated areas
• You're writing "and" in the decision statement
• Different stakeholders care about different parts

When NOT to Create an ADR

• Minor implementation details
• Obvious choices with no real alternatives
• Temporary decisions that will be revisited
• Style preferences (unless establishing standards)

ADR Maintenance

• Review ADRs quarterly for relevance
• Deprecate outdated decisions promptly
• Keep INDEX.md as the single source of truth
• Categories in INDEX.md should match project structure

Resources

references/

• adr-template.md: Standalone ADR template (30-50 lines target)
• index-template.md: INDEX.md template for new projects