/architecture-decision-records

name: architecture-decision-records
description: "Create and maintain Architecture Decision Records (ADRs) for significant technical choices—frameworks, data stores, API shapes, ML platform decisions. Use when documenting a decision, onboarding, or superseding a prior approach."
allowed-tools: Read, Glob, Grep

Architecture decision records

When to write an ADR

| Write ADR | Skip ADR | |-----------|----------| | New framework or major dependency | Minor version bump | | Database or storage choice | Bug fix | | API or integration pattern | Config-only change | | Security or auth architecture | Routine maintenance |

Lifecycle

`Proposed` -> `Accepted` -> `Deprecated` -> `Superseded`

Do not rewrite accepted ADRs; add a new ADR that supersedes the old one.

Required sections

1. **Context** — problem and constraints 2. **Decision** — what was chosen (one clear statement) 3. **Consequences** — positive, negative, risks and mitigations 4. **Status** and date

Optional (recommended for significant decisions)

• Decision drivers (numbered)
• Considered options with honest pros/cons
• Related ADRs / links

Lightweight template

# ADR-NNNN: Title

**Status:** Accepted | **Date:** YYYY-MM-DD

## Context
[Why we needed to decide]

## Decision
[What we decided]

## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... **Mitigation:** ...

Full MADR-style templates

See [reference.md](reference.md) for extended templates (standard, Y-statement, deprecation).

Practices

• Write before implementation starts when possible.
• Keep ADRs short (1-2 pages); link deep dives elsewhere.
• Be honest about trade-offs.