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