| name | adr-write |
| description | Write an Architecture Decision Record (ADR) for the current task, session, or branch. Gathers context from git branch name, recent commits, conversation tasks, and plans, then writes a well-structured ADR to the project's adrs directory. Use when the user says "write an ADR", "record this decision", "document this in the ADR", or invokes /adr-write.
|
Write an ADR capturing the architectural decision from the current work. Follow these steps exactly.
Step 1 — Gather context
Collect all available context before writing anything:
- Git branch: run
git branch --show-current to get the branch name — it often names the feature.
- Recent commits: run
git log --oneline -20 to see what has been done.
- Git diff summary: run
git diff main...HEAD --stat (or master...HEAD) to see what files changed.
- Conversation context: review any tasks, plans, or discussion in the current session about what was built and why.
- Existing ADRs: list files in the project's
adrs directory to avoid duplicating a recent ADR and to find related ones to link.
If after gathering context you still cannot determine what decision was made and why, ask the user one focused question before proceeding.
Step 2 — Identify the ADR directory
Look for the ADR directory in this order:
adr/content/adrs/ relative to the repo rootadrs/ relative to the repo rootadrs/ relative to the current working directory
Use whichever exists. If none exist, tell the user and ask where to put it.
Step 3 — Draft the ADR
Use this exact structure and frontmatter format, matching the existing ADRs in the directory:
---
date: YYYY-MM-DD
title: <Title Case title — concise, noun-phrase>
recordStatus: proposed
tags:
- <relevant tags, e.g. ruby, web, scheduler, api, etc.>
---
# Context - Why are we doing this?
<2–4 paragraphs. What problem exists? What constraints apply? What existing
system or ADR does this build on? Link to related ADRs with [Title](/adrs/slug).
## What already exists
<If relevant: describe the current state of the code, entity, or system that
this decision extends or changes. Omit if building from scratch.>
# Decision - What are we doing?
<Explain the approach chosen. If multiple options were considered, use this format:>
## <Sub-decision name>
**Option A — <name>**
<description>
**Pros:** ...
**Cons:** ...
**Option B — <name>**
<description>
**Pros:** ...
**Cons:** ...
**Decision: Option A**
<One paragraph justifying the choice.>
<If only one approach was taken with no alternatives, describe it directly without the options format.>
# Consequences - What will be different?
<Bullet list of concrete changes: new entities, deprecated paths, new flags,
deferred work, things that are now possible or impossible. Be specific.>
Step 4 — Choose the filename
Format: YYYYMMDD-short-hyphenated-summary.md
- Use today's date (check system date if unsure)
- Keep the slug short: 3–6 words, lowercase, hyphens
- Match the naming style of existing ADRs in the directory
Step 5 — Write the file
Write the ADR to the identified directory with the chosen filename. Show the user the full path.
Step 6 — Confirm and offer to adjust
Tell the user:
- The file path written
- The
recordStatus (default: proposed — change to accepted if the decision is already implemented and merged)
- Offer to adjust title, tags, status, or any section content
Rules
Do include:
- Links to related ADRs (use the
/adrs/slug format matching existing links)
- The specific technical trade-offs that were actually considered
- Deferred decisions explicitly called out in Consequences
- Feature flags if one was introduced
Do not include:
- Implementation detail that belongs in code comments
- Task tracking or ticket numbers (those belong in commit messages)
- Anything speculative about future work beyond what was explicitly discussed
- "This was generated by Claude" or any AI attribution
recordStatus values: proposed (default), accepted, deprecated, superseded
Boundaries
Writes one ADR per invocation. Does not commit the file — the user or CLAUDE.md conventions handle that. Does not modify existing ADRs unless the user explicitly asks.
