/adr-skill

name: adr-skill
description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
metadata:
  internal: true

ADR Skill

Philosophy

ADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.

This means:

• Constraints must be explicit and measurable, not vibes
• Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
• Consequences must map to concrete follow-up tasks
• Non-goals must be stated to prevent scope creep
• The ADR must be self-contained — no tribal knowledge assumptions
• **The ADR must include an implementation plan** — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly

When to Write an ADR

Write an ADR when a decision:

• **Changes how the system is built or operated** (new dependency, architecture pattern, infrastructure choice, API design)
• **Is hard to reverse** once code is written against it
• **Affects other people or agents** who will work in this codebase later
• **Has real alternatives** that were considered and rejected

Do NOT write an ADR for:

• Routine implementation choices within an established pattern
• Bug fixes or typo corrections
• Decisions already captured in an existing ADR (update it instead)
• Style preferences already covered by linters or formatters

When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.

Proactive ADR Triggers (For Agents)

If you are an agent coding in a repo and you encounter any of these situations, **stop and propose an ADR** before continuing:

• You are about to introduce a new dependency that doesn't already exist in the project
• You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow
• You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious
• You are about to change something that contradicts an existing accepted ADR
• You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR

**How to propose**: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.

Creating an ADR: Four-Phase Workflow

Every ADR goes through four phases. Do not skip phases.

Phase 0: Scan the Codebase

Before asking any questions, gather context from the repo:

1. **Find existing ADRs.** Check `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/` for existing records. Read them. Note:

• Existing conventions (directory, naming, template style)
• Decisions that relate to or constrain the current one
• Any ADRs this new decision might supersede

2. **Check the tech stack.** Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.

3. **Find related code patterns.** If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.

4. **Check for ADR references in code.** Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.

5. **Note what you found.** Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.

Phase 1: Capture Intent (Socratic)

Interview the human to understand the decision space. Ask questions **one at a time**, building on previous answers. Do not dump a list of questions.

**Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):

1. **What are you deciding?** — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W"). 2. **Why now?** — What broke, what's changing, or what will break if you do nothing? This is the trigger. 3. **What constraints exist?** — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 ("I see you're already using X — does that constrain this?"). 4. **What does success look like?** — Measurable outcomes. Push past "it works" to specifics (latency, throughput, DX, maintenance burden). 5. **What options have you considered?** — At least two. For each: what's the core tradeoff? If they only have one option, help them articulate why alternatives were rejected. 6. **What's your current lean?** — Capture gut intuition early. Often reveals unstated priorities. 7. **Who needs to know or approve?** — Decision-makers, consulted experts, informed stakeholders. 8. **What would an agent need to implement this?** — Which files/directories are affected? What existing patterns should it follow? What should it avoid? What tests would prove it's working? This directly feeds the Implementation Plan.

**Adaptive follow-ups**: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:

• "What's the worst-case outcome if this decision is wrong?"
• "What would make you revisit this in 6 months?"
• "Is there anything you're explicitly choosing NOT to do?"
• "What prior ar