ADR Writing Skill

Use this skill whenever a meaningful technical/architecture decision has been made (or is being proposed) and it should be recorded for future maintainers.

When to activate this skill

• User introduces or replaces a major dependency
• User changes package/module boundaries or public API surface
• User adopts a new pattern that should be repeated
• User changes data models with compatibility/migration implications
• User makes a decision that is hard to reverse or has non-obvious trade-offs
• User asks about documenting architecture decisions

Definition: “Architecture decision”

Write an ADR if the decision is likely to matter in 1–6 months to someone other than the author.

Examples that require an ADR:

• introducing or replacing a major dependency (e.g., persistence, networking, analytics)
• changing package/module boundaries or public API surface
• adopting a new pattern that should be repeated (state management approach, service boundaries)
• changing data models with compatibility/migration implications
• decisions that are hard to reverse or have non-obvious trade-offs

Examples that typically do NOT need an ADR:

• small refactors localized to one file
• renames, formatting, and mechanical cleanups
• fixes that don’t change behavior or long-term direction

Where ADRs live

All ADRs live in docs/adrs/.

• Index and conventions: docs/adrs/README.md
• Template: docs/adrs/0000-template.md

Naming and numbering

Use a monotonic numeric prefix:

• 0001-short-decision-title.md
• 0002-some-other-decision.md

Rules:

• pick the next available number in docs/adrs/
• filenames are lowercase, words separated by hyphens
• never renumber existing ADRs

Status model

Allowed statuses:

• Proposed
• Accepted
• Deprecated
• Superseded by 000X-...

Guidance:

• If writing before merging a change, use Proposed.
• When the change lands, update to Accepted.
• If the decision is replaced, mark the old ADR as Superseded; do not delete it.

ADR content requirements

An ADR must include (in this order):

1. YAML frontmatter at the very top of the file (first line) with date and status
2. Title line: # NNNN: <Decision Title>
3. Context
4. Decision
5. Alternatives considered
6. Consequences
7. References (PR/issue/related docs)

Keep it short and concrete:

• Prefer specific “we will…” statements.
• Name the impacted modules/files at a high level (don’t paste code).
• Record the trade-offs that caused debate.

Workflow (what to do when you detect a decision)

When the user asks for a change that implies an architectural choice (or you notice one while implementing):

1. Search docs/adrs/ for an existing ADR that already covers the decision.
2. If none exists, create a new ADR using docs/adrs/0000-template.md.
3. Add the ADR to docs/adrs/README.md index.
4. If implementation changes are part of the same work, ensure the ADR’s decision matches what was actually implemented.

Writing style constraints

• Avoid sensitive data and secrets.
• Don’t include personal opinions or blame.
• Avoid vendor marketing language.
• Prefer “we chose X because…” over lengthy background.

“Definition of done” checklist

Before finishing:

• ADR file created under docs/adrs/ with next number
• Status set correctly (Proposed vs Accepted)
• At least 1 real alternative recorded
• Consequences include at least 1 downside
• docs/adrs/README.md index updated
• References include the PR/issue link if available

Project-specific notes

This section can be customized per-project. Common patterns:

• ADRs typically live in docs/adrs/ or docs/adr/
• Some projects use doc/architecture/decisions/
• Verify the ADR location exists before creating new ADRs
• Run project tests after implementing changes that accompany an ADR