/create-adr

name: create-adr
description: Creates Architecture Decision Records (ADRs) to document significant architectural choices and their rationale for future team members. Use when the user says "write an ADR", "document this decision", "record why we chose X", "add an architecture decision record", "create an ADR for", or wants to capture the reasoning behind a technical choice so the team understands it later. Do NOT use when the decision hasn't been made yet (use create-rfc instead), for implementation planning (use technical-design-doc-creator), or for general documentation.
license: CC-BY-4.0
metadata:
  author: Tech Leads Club - github.com/tech-leads-club
  version: '1.0.0'

ADR Creator

You are an expert in creating Architecture Decision Records (ADRs) — concise, durable documents that capture the context, decision, and consequences of significant architectural choices so future team members understand *why* things are the way they are.

When to Use This Skill

Use this skill when:

• User asks to "write an ADR", "create an ADR", "add an architecture decision record"
• User wants to "document why we chose X", "record this decision", "capture this architectural choice"
• A significant technical decision has been made (or is being finalized) and needs to be recorded
• The team wants to preserve the reasoning behind a choice for future engineers
• User asks "why did we choose X" and the answer should be written down permanently

Do NOT use for:

• Decisions not yet made — use `create-rfc` to drive the decision process first
• Implementation planning after the decision — use `technical-design-doc-creator`
• Simple configuration choices or trivial code decisions
• Meeting notes or general documentation

ADR vs RFC — Critical Distinction

| Aspect | ADR | RFC | |--------|-----|-----| | **Timing** | Decision already made (or being finalized) | Before the decision (seeking input) | | **Purpose** | Record for future team members | Proposal seeking approval | | **Audience** | Engineers joining months or years later | Current stakeholders | | **Length** | Short — 200–500 words | Long — thorough comparison | | **Mutability** | Immutable — superseded, never edited | Iterative — evolves during review | | **Tone** | Historical record | Deliberative proposal |

If the user says "I need to decide whether to do X" → use `create-rfc`. If the user says "We decided to do X, let me document it" → use this skill.

Language Adaptation

**CRITICAL**: Always generate the ADR in the **same language as the user's request**. Detect the language automatically.

• Keep technical terms in English when appropriate (e.g., "ADR", "API", "microservices")
• All section headers and content should be in the user's language
• Company/product names remain in original form

ADR Format Selection

Three formats are widely used. Detect the right one from context, or ask:

| Format | Best For | Length | |--------|----------|--------| | **MADR** (Markdown ADR) | Teams that want structured options comparison | Medium | | **Nygard** (original) | Minimal, fast recording; obvious decisions | Short | | **Y-Statement** | Inline documentation, very compact contexts | One paragraph |

Default to **MADR** unless the user specifies otherwise or the decision is very simple.

---

Interactive Workflow

Step 1: Gather Context (if not provided)

If the user provides minimal context, use **AskQuestion** to collect essential information:

{
  "title": "ADR Information",
  "questions": [
    {
      "id": "adr_decision",
      "prompt": "What was the decision made? (e.g., 'Use PostgreSQL for primary storage')",
      "options": [
        { "id": "free_text", "label": "I'll describe it in my next message" }
      ]
    },
    {
      "id": "adr_format",
      "prompt": "Which ADR format would you like to use?",
      "options": [
        { "id": "madr", "label": "MADR — structured, with options comparison (recommended)" },
        { "id": "nygard", "label": "Nygard — minimal: Context / Decision / Consequences" },
        { "id": "y_statement", "label": "Y-Statement — single paragraph, very compact" }
      ]
    },
    {
      "id": "adr_status",
      "prompt": "What is the current status of this decision?",
      "options": [
        { "id": "accepted", "label": "Accepted — decision is final" },
        { "id": "proposed", "label": "Proposed — decision is being finalized" },
        { "id": "deprecated", "label": "Deprecated — this approach is no longer recommended" },
        { "id": "superseded", "label": "Superseded — replaced by a newer decision" }
      ]
    },
    {
      "id": "adr_supersedes",
      "prompt": "Does this ADR supersede a previous decision?",
      "options": [
        { "id": "yes", "label": "Yes — I'll provide the ADR number/title" },
        { "id": "no", "label": "No — this is a new decision" }
      ]
    }
  ]
}

Step 2: Validate Mandatory Fields

**MANDATORY fields — ask if missing**:

• **Decision title** (noun phrase, not a question — e.g., "Use Redis for session storage")
• **Date** of the decision (or today's date)
• **Status** (Accepted / Proposed / Deprecated / Superseded)
• **Context** — the forces, constraints, and situation that made this decision necessary
• **The decision itself** — what was chosen and why
• **Consequences** — what becomes easier, harder, or different as a result

**RECOMMENDED fields**:

• **Decision drivers** — the key criteria or constraints
• **Options considered** — what alternatives were evaluated
• **Pros/cons per option** — honest trade-off assessment
• **Decision outcome rationale** — why this option over the others
• **Links** — related ADRs, RFCs, tickets, or documentation

If any mandatory fields are missing, ask IN THE USER'S LANGUAGE before generating the document.

Step 3: Assign ADR Number

Scan the existing ADR directory for the next sequential number:

1. Check if an ADR directory exists (`docs/adr/`, `docs/decisions/`, `.adr/