architecture-decision-record

name	architecture-decision-record
description	Creates Architecture Decision Records (ADRs) to document significant technical decisions — why a choice was made, what alternatives were considered, and what tradeoffs were accepted. Use when making or documenting important architectural choices, selecting a framework or library, or when the user asks to document a decision, write an ADR, or record a technical choice.

When to use

• Documenting significant architectural choices (framework, library, pattern, boundary)
• User asks to write an ADR, record a technical decision, or explain why something was chosen
• Decision is costly to reverse, affects multiple teams, or will prompt "why did we do this?"

On-demand loading: Read this skill only when the task clearly matches the description above or trigger phrases below. Do not load for unrelated work.

Architecture Decision Record (ADR)

Purpose

Capture significant architectural decisions so future engineers understand what was decided, why, what alternatives were rejected, and what tradeoffs were accepted.

When to write an ADR

Write an ADR when the decision:

• Is difficult or costly to reverse
• Affects multiple components or teams
• Introduces a new dependency, pattern, or architectural boundary
• Will cause future engineers to ask "why did they do it this way?"

Skip ADRs for low-stakes, easily reversible, or purely stylistic choices.

Process

1. Understand the decision context

Ask the user (or infer from context):

• What problem were you solving?
• What options did you consider?
• What constraints existed (time, team, compatibility, cost)?
• What did you choose, and what were you willing to give up?

2. Check for existing ADRs

Look in: docs/adr/, docs/decisions/, adr/, or wherever the repo stores them.

• If a directory exists, follow its naming convention
• If none exists, create docs/adr/ and a README.md there explaining the convention

3. Determine the ADR number

Scan existing ADR files for the highest number, increment by 1. Use 0001, 0002, etc.

4. Write the ADR

Use the template in references/adr-template.md. Keep it brief and honest.

Output

After writing the ADR:

1. Present the draft for review
2. Ask: "Should I place this in docs/adr/ and create the directory if it doesn't exist?"
3. Write the file on confirmation
4. Optionally: add a one-line code comment linking to the ADR at the decision point in code

References

File	Contents
references/adr-template.md	Full ADR template, file naming, status lifecycle, quality checklist