---

name: Capturing Decisions description: Create and maintain MADR-format Architectural Decision Records in Markdown under docs/decisions. Use when the user wants to document important decisions.

MADR ADRs

This skill creates (and keeps tidy) Architectural Decision Records (ADRs) using MADR (Markdown Architectural Decision Records) v4.0.0.

A helpful bar for what "counts" as an architectural decision is Martin Fowler's: "a decision you wish you could get right early." ("Who needs an architect?", IEEE Software, 2003)

Primary reference: Markdown Architectural Decision Records

Repository layout and naming

All ADRs live in:

• docs/decisions/NNNN-title-with-dashes.md

Where:

• NNNN is a zero-padded 4-digit sequence number (0001, 0002, …)
• title-with-dashes is a lowercase slug (letters/digits/hyphens)

If docs/decisions/ does not exist yet, create it.

Template

Use this copy of the MADR 4.0.0 long-form template

Create new ADRs by copying the template and replacing placeholders. Optional sections may be removed (the template marks them clearly).

Required metadata

Each ADR must include YAML front matter at the top with:

• status: one of proposed, accepted, rejected, deprecated, or superseded by ADR-NNNN
• date: YYYY-MM-DD (update when the ADR is materially changed)

Status emoji for the index

Maintain an index at docs/decisions/README.md that lists all ADRs with:

• status emoji
• ADR title (matching the H1 of the ADR), as a link to the full ADR
• date last updated

Use this mapping:

• 🟡 proposed
• ✅ accepted
• ❌ rejected
• ⚠️ deprecated
• 🔁 superseded

Process

1. Pick the next number by scanning existing ADR filenames in docs/decisions/ and incrementing the highest NNNN. Start at 0001 if none exist.
2. Slugify the title into title-with-dashes (lowercase, hyphens, no punctuation).
3. Create the ADR from ADR_TEMPLATE.md.
   • Default status to proposed unless the change set includes implementation and agreement to accept.
4. Update docs/decisions/README.md:
   • Add the ADR in numeric order.
   • Ensure the emoji matches the ADR's status.
5. If an ADR is superseded, keep the old ADR file, set its status to superseded by ADR-NNNN, and update the index row emoji to 🔁.

Output expectations

• ADR markdown should be clean and readable in GitHub rendering.
• Keep ADRs concise, but include enough context that a new reader can understand why the decision was made.