architecture-decision-record

name	architecture-decision-record
description	Use when choosing between competing technical approaches, recording why an architecture decision (ADR) was made, or revisiting a previous ADR

Architecture Decision Record

Overview

Create architecture decision records (ADRs) following the MADR (Markdown Any Decision Records) standard. ADRs capture the context, options considered, and rationale behind significant architecture decisions.

The ADR template contains the full MADR document structure ready to copy into a project. Optional sections are marked with HTML comments and can be removed for a minimal ADR. This skill describes when and how to use it.

Announce at start: "I'm using the architecture-decision-record skill to create an ADR following the MADR standard."

When to Use

• Making a significant technical or architecture decision
• Choosing between multiple implementation approaches
• Documenting a decision that was already made but not recorded
• Revisiting or superseding a previous decision

When NOT to Use

• Trivial implementation choices that don't affect architecture
• Decisions already documented elsewhere (e.g., in a spec or design doc)

Workflow

1. Identify the Decision

Ask:

• What problem are we solving?
• What constraints are we working within?
• Who are the decision-makers and who should be consulted?

2. Discover ADR Location

Use the plan location discovery process to find the right directory. When searching for existing directories, also check for ADR-specific locations: docs/decisions/, docs/adr/, docs/ADRs/, docs/architecture/decisions/. If no ADR directory exists, default to docs/decisions/.

Announce the chosen path and wait for user confirmation before writing.

3. Determine Next Number

List existing ADRs in the directory and use the next sequential number. Pad with leading zeros to match existing convention (e.g., 0001, 0012). Default to 4-digit padding.

4. Walk Through MADR Sections

Guide the user through each section using the ADR template. Do not skip required sections. For optional sections, ask if the user wants to include them. A minimal ADR only needs the three required sections.

Required sections:

• Context and Problem Statement
• Considered Options
• Decision Outcome

Optional sections (remove if not needed):

• YAML frontmatter (status, date, decision-makers, consulted, informed)
• Decision Drivers
• Consequences (Good/Bad)
• Confirmation (how to verify the decision was implemented correctly)
• Pros and Cons of the Options
• More Information (links, references, related ADRs)

5. Write the ADR

Copy the template and fill in each section. File naming: NNNN-title-in-kebab-case.md.

Statuses

Status	Meaning
proposed	Decision is under discussion, not yet agreed upon
accepted	Decision has been agreed upon and should be followed
rejected	Decision was considered but not adopted
deprecated	Decision is no longer relevant or recommended
superseded by ADR-NNNN	Replaced by a newer decision; link to the successor

When superseding an ADR, update the old ADR's status to point to the new one.

Common Mistakes

• Writing the ADR after implementation is done and framing it as a foregone conclusion
• Listing options without genuine pros and cons analysis
• Missing the "why" in Decision Outcome, just stating the choice without justification
• Not listing who was consulted or informed
• Creating ADRs for trivial decisions that don't warrant the overhead