adr-skill

1---2name: adr-skill3description: 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.4metadata:5  internal: true6---7 8# ADR Skill9 10## Philosophy11 12ADRs 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.13 14This means:15 16- Constraints must be explicit and measurable, not vibes17- Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")18- Consequences must map to concrete follow-up tasks19- Non-goals must be stated to prevent scope creep20- The ADR must be self-contained — no tribal knowledge assumptions21- **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 correctly22 23## When to Write an ADR24 25Write an ADR when a decision:26 27- **Changes how the system is built or operated** (new dependency, architecture pattern, infrastructure choice, API design)28- **Is hard to reverse** once code is written against it29- **Affects other people or agents** who will work in this codebase later30- **Has real alternatives** that were considered and rejected31 32Do NOT write an ADR for:33 34- Routine implementation choices within an established pattern35- Bug fixes or typo corrections36- Decisions already captured in an existing ADR (update it instead)37- Style preferences already covered by linters or formatters38 39When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.40 41### Proactive ADR Triggers (For Agents)42 43If you are an agent coding in a repo and you encounter any of these situations, **stop and propose an ADR** before continuing:44 45- You are about to introduce a new dependency that doesn't already exist in the project46- 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 follow47- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious48- You are about to change something that contradicts an existing accepted ADR49- You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR50 51**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.52 53## Creating an ADR: Four-Phase Workflow54 55Every ADR goes through four phases. Do not skip phases.56 57### Phase 0: Scan the Codebase58 59Before asking any questions, gather context from the repo:60 611. **Find existing ADRs.** Check `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/` for existing records. Read them. Note:62   - Existing conventions (directory, naming, template style)63   - Decisions that relate to or constrain the current one64   - Any ADRs this new decision might supersede65 662. **Check the tech stack.** Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.67 683. **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.69 704. **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.71 725. **Note what you found.** Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.73 74### Phase 1: Capture Intent (Socratic)75 76Interview the human to understand the decision space. Ask questions **one at a time**, building on previous answers. Do not dump a list of questions.77 78**Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):79 801. **What are you deciding?** — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W").812. **Why now?** — What broke, what's changing, or what will break if you do nothing? This is the trigger.823. **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?").834. **What does success look like?** — Measurable outcomes. Push past "it works" to specifics (latency, throughput, DX, maintenance burden).845. **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.856. **What's your current lean?** — Capture gut intuition early. Often reveals unstated priorities.867. **Who needs to know or approve?** — Decision-makers, consulted experts, informed stakeholders.878. **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.88 89**Adaptive follow-ups**: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:90 91- "What's the worst-case outcome if this decision is wrong?"92- "What would make you revisit this in 6 months?"93- "Is there anything you're explicitly choosing NOT to do?"94- "What prior art or existing patterns in the codebase does this relate to?"95- "I found [existing ADR/pattern] — does this new decision interact with it?"96 97**When to stop**: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.98 99**Intent Summary Gate**: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:100 101> **Here's what I'm capturing for the ADR:**102>103> - **Title**: {title}104> - **Trigger**: {why now}105> - **Constraints**: {list}106> - **Options**: {option 1} vs {option 2} [vs ...]107> - **Lean**: {which option and why}108> - **Non-goals**: {what's explicitly out of scope}109> - **Related ADRs/code**: {what exists that this interacts with}110> - **Affected files/areas**: {where in the codebase this lands}111> - **Verification**: {how we'll know it's implemented correctly}112>113> **Does this capture your intent? Anything to add or correct?**114 115Do NOT proceed to Phase 2 until the human confirms the summary.116 117### Phase 2: Draft the ADR118 1191. **Choose the ADR directory.**120   - If one exists (found in Phase 0), use it.121   - If none exists, create `contributing/decisions/` (if `contributing/` exists), `docs/decisions/` (MADR default), or `adr/` (simpler repos).122 1232. **Choose a filename strategy.**124   - If existing ADRs use date prefixes (`YYYY-MM-DD-...`), continue that.125   - Otherwise use slug-only filenames (`choose-database.md`).126 1273. **Choose a template.**128   - Use `assets/templates/adr-simple.md` for straightforward decisions (one clear winner, minimal tradeoffs).129   - Use `assets/templates/adr-madr.md` when you need to document multiple options with structured pros/cons/drivers.130   - See `references/template-variants.md` for guidance.131 1324. **Fill every section from the confirmed intent summary.** Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).133 1345. **Write the Implementation Plan.** This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.135 1366. **Write Verification criteria as checkboxes.** These must be specific enough that an agent can programmatically or manually check each one.137 1387. **Generate the file.**139   - Preferred: run `scripts/new_adr.js` (handles directory, naming, and optional index updates).140   - If you can't run scripts, copy a template from `assets/templates/` and fill it manually.141 142### Phase 3: Review Against Checklist143 144After drafting, review the ADR against the agent-readiness checklist in `references/review-checklist.md`.145 146**Present the review as a summary**, not a raw checklist dump. Format:147 148> **ADR Review**149>150> ✅ **Passes**: {list what's solid — e.g., "context is self-contained, implementation plan covers affected files, verification criteria are checkable"}151>152> ⚠️ **Gaps found**:153>154> - {specific gap 1 — e.g., "Implementation Plan doesn't mention test files — which test suite should cover this?"}155> - {specific gap 2}156>157> **Recommendation**: {Ship it / Fix the gaps first / Needs more Phase 1 work}158 159Only surface failures and notable strengths — do not recite every passing checkbox.160 161If there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.162 163Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.164 165## Consulting ADRs (Read Workflow)166 167Agents should read existing ADRs **before implementing changes** in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.168 169### When to Consult ADRs170 171- Before starting work on a feature that touches architecture (auth, data layer, API design, infrastructure)172- When you encounter a pattern in the code and wonder "why is it done this way?"173- Before proposing a change that might contradict an existing decision174- When a human says "check the ADRs" or "there's a decision about this"175- When you find an ADR reference in a code comment176 177### How to Consult ADRs178 1791. **Find the ADR directory.** Check `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/`. Also check for an index file (`README.md` or `index.md`).180 1812. **Scan titles and statuses.** Read the index or list filenames. Focus on `accepted` ADRs — these are active decisions.182 1833. **Read relevant ADRs fully.** Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.184 1854. **Respect the decisions.** If an accepted ADR says "use PostgreSQL," don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.186 1875. **Follow the Implementation Plan.** When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says "all new queries go through the data-access layer in `src/db/`," do that.188 1896. **Reference ADRs in your work.** Add ADR references in code comments and PR descriptions (see "Code ↔ ADR Linking" below).190 191## Code ↔ ADR Linking192 193ADRs should be bidirectionally linked to the code they govern.194 195### ADR → Code (in the Implementation Plan)196 197The Implementation Plan section names specific files, directories, and patterns:198 199```markdown200## Implementation Plan201 202- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`203- **Pattern**: all database queries go through `src/db/client.ts`204```205 206### Code → ADR (in comments)207 208When implementing code guided by an ADR, add a comment referencing it:209 210```typescript211// ADR: Using better-sqlite3 for test database212// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md213import Database from 'better-sqlite3';214```215 216Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.217 218### Why This Matters219 220- An agent working in `src/db/` can find which ADRs govern that area221- An agent reading an ADR can find the code that implements it222- When an ADR is superseded, the code references make it easy to find all code that needs updating223 224## Other Operations225 226### Update an Existing ADR227 2281. Identify the intent:229   - **Accept / reject**: change status, add any final context.230   - **Deprecate**: status → `deprecated`, explain replacement path.231   - **Supersede**: create a new ADR, link both ways (old → new, new → old).232   - **Add learnings**: append to `## More Information` with a date stamp. Do not rewrite history.233 2342. Use `scripts/set_adr_status.js` for status changes (supports YAML front matter, bullet status, and section status).235 236### Post-Acceptance Lifecycle237 238After an ADR is accepted:239 2401. **Create implementation tasks.** Each item in the Implementation Plan and each follow-up in Consequences should become a trackable task (issue, ticket, or TODO).2412. **Reference the ADR in PRs.** Link to the ADR in PR descriptions, e.g. "Implements `contributing/decisions/2025-06-15-use-sqlite-for-test-database.md`."2423. **Add code references.** Add ADR path comments at key implementation points.2434. **Check verification criteria.** Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in `## More Information`.2445. **Revisit when triggers fire.** If the ADR specified revisit conditions ("if X happens, reconsider"), monitor for those conditions.245 246### Index247 248If the repo has an ADR index/log file (often `README.md` or `index.md` in the ADR dir), keep it updated.249 250Preferred: let `scripts/new_adr.js --update-index` do it. Otherwise:251 252- Add a bullet entry for the new ADR.253- Keep ordering consistent (numeric if numbered; date or alpha if slugs).254 255### Bootstrap256 257When introducing ADRs to a repo that has none:258 259```bash260node /path/to/adr-skill/scripts/bootstrap_adr.js261```262 263This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use `--json` for machine-readable output. Use `--dir` to override the directory name.264 265### Categories (Large Projects)266 267For repos with many ADRs, organize by subdirectory:268 269```270docs/decisions/271  backend/272    2025-06-15-use-postgres.md273  frontend/274    2025-06-20-use-react.md275  infrastructure/276    2025-07-01-use-terraform.md277```278 279Date prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.280 281## Resources282 283### scripts/284 285- `scripts/new_adr.js` — create a new ADR file from a template, using repo conventions.286- `scripts/set_adr_status.js` — update an ADR status in-place (YAML front matter or inline). Use `--json` for machine output.287- `scripts/bootstrap_adr.js` — create ADR dir, `README.md`, and initial "Adopt ADRs" decision.288 289### references/290 291- `references/review-checklist.md` — agent-readiness checklist for Phase 3 review.292- `references/adr-conventions.md` — directory, filename, status, and lifecycle conventions.293- `references/template-variants.md` — when to use simple vs MADR-style templates.294- `references/examples.md` — filled-out short and long ADR examples with implementation plans.295 296### assets/297 298- `assets/templates/adr-simple.md` — lean template for straightforward decisions.299- `assets/templates/adr-madr.md` — MADR 4.0 template for decisions with multiple options and structured tradeoffs.300- `assets/templates/adr-readme.md` — default ADR index scaffold used by `scripts/bootstrap_adr.js`.301 302### Script Usage303 304From the target repo root:305 306```bash307# Simple ADR308node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed309 310# MADR-style with options311node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed312 313# With index update314node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index315 316# Bootstrap a new repo317node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions318```319 320Notes:321 322- Scripts auto-detect ADR directory and filename strategy.323- Use `--dir` and `--strategy` to override.324- Use `--json` to emit machine-readable output.325