Architecture Decision Records

Iron Law: Every significant technical decision must produce an ADR before implementation begins; never let irreversible decisions proceed without a documented record.

Architecture Decision Records

Capture the context and rationale behind significant technical decisions using structured ADR formats.

When to Use This Skill

Implicit Trigger Detection

Recognize these conversation patterns as ADR signals — ask "Should we document this as an ADR?" before proceeding:

Rule: If the decision affects more than one service, involves a new dependency, or cannot easily be reversed — it needs an ADR.

Quick Start

1. Copy the template: cp docs/adr/template.md docs/adr/NNNN-your-title.md
2. Fill in: Context, Decision Drivers, Options, Decision, Consequences
3. PR for review (2+ senior engineers)
4. Update docs/adr/README.md index after merge

Core Concepts

An Architecture Decision Record captures:

• Context: Why we needed to make a decision
• Decision: What we decided
• Consequences: What happens as a result

ADR Lifecycle

Proposed --> Accepted --> Deprecated --> Superseded
                |
             Rejected

Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.

Process

1. Choose a Template

Pick the format that fits the decision's complexity:

For Standard MADR (significant decisions): Score each considered option using the dual-lens rubric in reference/adr-scoring.md before selecting a winner. Include the ## Option Scoring table in the ADR. If the winning option is not ADOPT, state mitigations explicitly in the Decision section.

Read reference/adr-templates.md for all template formats ready to copy-paste.

2. Write the ADR

• Start with context -- explain the problem before the solution
• List 2-3 real alternatives with honest pros/cons and explicit "why not" reasoning (see Alternatives Considered below)
• State the decision clearly
• Document both positive and negative consequences with specifics

3. Review and Approve

• Submit as PR with 2+ senior engineer reviewers
• Consult affected teams
• Assess security, cost, and reversibility implications

4. Maintain

• Update ADR index after acceptance
• Create implementation tickets
• Never edit accepted ADRs -- write new ones to supersede

Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).

Alternatives Considered

For each alternative: document pros, cons, AND why it was ultimately rejected. The "why not" is as valuable as the decision itself — it prevents relitigating the same choices.

Rule: A vague "not chosen" entry (e.g. "too complex") is not acceptable. State the specific constraint, risk, or tradeoff that ruled it out in this context.

Minimal Template (Copy-Paste Starter)

# ADR-NNNN: [Title]

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Context
[Why do we need to decide this? What's the problem?]

## Decision
We will [decision].

## Consequences
- **Good**: [benefits]
- **Bad**: [drawbacks]
- **Mitigations**: [how we'll address the bad]

Common Mistakes

Directory Structure

docs/adr/
  README.md           # Index of all ADRs
  template.md         # Team's ADR template
  0001-use-postgresql.md
  0002-caching-strategy.md

Reference Files

Resources

• MADR Template
• ADR GitHub Organization
• adr-tools

Error Handling

Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.

Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.