| name | mpm-adr |
| description | Architecture Decision Records (ADRs) — opt-in convention for documenting significant, hard-to-reverse architectural decisions using the Nygard template. |
| user-invocable | true |
| version | 1.0.0 |
| category | mpm-command |
| tags | ["mpm-command","documentation","architecture","adr","pm-optional"] |
/mpm-adr
Architecture Decision Records (ADRs) are short, structured documents that capture why a significant architectural decision was made — not just what was decided. They live alongside the code so future contributors understand the constraints and trade-offs that shaped the system.
This skill is opt-in. Only use it for decisions that are architecturally significant AND costly to reverse. Over-forcing ADRs on routine work is the documented adoption-killer.
When to Write an ADR
Write an ADR only when all three conditions are true:
- Architecturally significant — the decision shapes how major parts of the system are structured, constrain future options, or affect multiple teams/components.
- Costly to reverse — undoing or changing the decision later would require substantial rework, data migration, or coordination.
- Not obvious from the code — the rationale is not apparent from reading the implementation alone.
Write an ADR for:
- Choosing a database engine or persistence strategy
- Adopting an async framework or concurrency model
- Selecting an authentication/authorization approach
- Defining service boundaries or API contracts
- Committing to a major dependency or platform
- Establishing a cross-cutting pattern (error handling, logging format)
- Deprecating a foundational component
Do NOT write an ADR for:
- Routine bug fixes
- Small features or minor enhancements
- Style/formatting decisions (use a linter config)
- Decisions already obvious from the codebase
- Every library version bump
If you are unsure, ask: "Would a new team member in six months need to understand why this choice was made?" If no — skip it.
File Location Convention
| Scope | Location |
|---|
| Workspace-wide decisions | docs/adr/NNNN-kebab-title.md |
| Component-specific decisions | docs/<component>/decisions/NNNN-kebab-title.md |
Use docs/adr/ for decisions that span the whole project or affect architectural boundaries. Use docs/<component>/decisions/ for decisions scoped to a single service or library within a monorepo.
Numbering Convention
ADRs are numbered sequentially with zero-padded four-digit integers:
docs/adr/
0000-template.md ← master template (never a real decision)
0001-use-postgres.md
0002-adopt-async-framework.md
0003-api-versioning-strategy.md
Pick the next available number by listing existing files:
ls docs/adr/ | sort | tail -5
Status Lifecycle
Every ADR carries a Status field with one of these values:
| Status | Meaning |
|---|
Proposed | Draft under discussion; not yet adopted |
Accepted | Adopted — this is the current approach |
Deprecated | No longer recommended; superseded or abandoned |
Superseded by [NNNN] | Replaced by a later ADR (link to the new one) |
When a decision changes, update the old ADR's status to Superseded by NNNN and create a new ADR for the replacement. Never delete old ADRs — the historical record is the point.
Nygard Template
# NNNN. Title (short, imperative: "Use X for Y")
Date: YYYY-MM-DD
## Status
Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-replacement.md)
## Context
What is the issue that we are seeing that is motivating this decision?
Describe the forces at play: technical constraints, team constraints,
organizational constraints, product requirements. Be factual.
## Decision
The change that we are proposing or have agreed to implement.
State the decision clearly in active voice: "We will use X."
## Consequences
What becomes easier or more difficult as a result of this change?
List both positive and negative consequences. Include known risks.
Be honest about trade-offs — this section is the most valuable part.
Workflow
Creating a new ADR
- Run
/mpm-init on a new project — docs/adr/ is scaffolded with README.md and 0000-template.md.
- Copy
0000-template.md to NNNN-your-title.md with the next number.
- Fill in Context, Decision, and Consequences. Set Status to
Proposed.
- Submit for review. Once agreed, change Status to
Accepted.
- Commit with:
docs: ADR-NNNN adopt X for Y
Superseding an ADR
- Create a new ADR (
MMMM-new-approach.md) with Status Accepted.
- Edit the old ADR's Status to
Superseded by [MMMM](MMMM-new-approach.md).
- Commit both files together.
Follow-up (Stretch Goal)
A future documentation-agent hook could auto-draft ADRs from significant commits or conversation context. This is tracked as a follow-up to issue #562 and is not part of the current implementation.
References
- Michael Nygard, "Documenting Architecture Decisions" (2011)
- bobmatnyc/trusty-tools — prior art for this convention
docs/features/adr.md — trigger criteria and hybrid location guide
