Architecture Decision Records Skill

Architecture Decision Records

Create and manage Architecture Decision Records following project conventions with automatic numbering and index maintenance.

Auto-Invoke Triggers

This skill automatically activates when:

Keywords: "ADR", "architecture decision", "document this decision", "record the decision"
Editing ADR files: Files in docs/adr/, doc/adr/, architecture/decisions/, .adr/
Discussing architectural choices: Framework selection, technology decisions, pattern choices

What This Skill Delivers

1. ADR Creation

Auto-detect project's ADR directory
Auto-number ADRs (scan existing, increment)
Adapt to project's existing template style
Offer MADR 4.0 enhancements as optional additions

2. Directory Discovery

Search order for ADR directories:

docs/adr/
doc/adr/
architecture/decisions/
.adr/
Create docs/adr/ if none exists

3. Template Detection

Analyze existing ADRs to detect:

Naming convention: NNNN-kebab-case-title.md or NNN-title.md
Section structure: Status, Context, Decision, Consequences
Optional sections: Decision Drivers, Pros/Cons, Confirmation

4. Index Maintenance

Automatically update README.md with ADR table: | Number | Title | Status | Date | |--------|-------|--------|------|

5. Supersession Workflow

When replacing an ADR:

Mark old ADR status as "Superseded by [ADR-NNNN]"
Link new ADR with "Supersedes [ADR-NNNN]"
Update README.md index

Core Template Sections

Required (Minimal)

Status: Proposed | Accepted | Deprecated | Superseded
Date: ISO 8601 format (YYYY-MM-DD)
Context and Problem Statement: 2-3 sentences describing the situation
Decision: What was decided and why
Consequences: Positive and negative impacts

Optional Enhancements (MADR 4.0)

Technical Story: Link to issue/spec (e.g., #123)
Decision Drivers: Bulleted list of forces/concerns
Decision Makers: Who made this decision
Consulted: Stakeholders whose opinions were sought
Informed: Stakeholders who need to know
Considered Options: List of alternatives evaluated
Pros and Cons: Detailed analysis per option
Confirmation: How to validate the decision was implemented

Quick Start

Create New ADR

# Auto-invoke by saying:
"Document the decision to use PostgreSQL over MongoDB"
"Create an ADR for our authentication approach"
"I need to record why we chose React Query"

Supersede Existing ADR

"Supersede ADR-0005 with a new caching strategy"
"Replace our database decision ADR with the new approach"

Scripts

Located in scripts/ directory, using uv for execution:

adr_create.py

uv run scripts/adr_create.py --title "Use PostgreSQL for persistence"
uv run scripts/adr_create.py --title "..." --template madr --create-dir

adr_index.py

uv run scripts/adr_index.py --dir docs/adr
uv run scripts/adr_index.py --dir docs/adr --dry-run

adr_supersede.py

uv run scripts/adr_supersede.py --old 5 --new 12 --dir docs/adr

Output Example

# ADR-0012: Use PostgreSQL for Data Persistence

## Status
Accepted

## Date
2026-01-10

## Context and Problem Statement
We need a reliable database solution for our microservices architecture
that supports complex queries and ACID transactions.

## Decision
Chosen option: PostgreSQL, because it provides the best balance of
ACID compliance, query flexibility, and team familiarity.

## Consequences
**Positive:**
- Full ACID transaction support
- Mature ecosystem and tooling

**Negative:**
- Horizontal scaling requires more setup

Progressive Disclosure

Level 2: WORKFLOW.md - Step-by-step methodology
Level 3: EXAMPLES.md - Real-world ADR examples
Level 4: TROUBLESHOOTING.md - Error handling

Related Resources

MADR 4.0 Template: https://adr.github.io/madr/
ADR GitHub Organization: https://github.com/adr

Agent Skills: Architecture Decision Records

Install this agent skill to your local

Skill Files