adr-write

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:

1. Git branch: run git branch --show-current to get the branch name — it often names the feature.
2. Recent commits: run git log --oneline -20 to see what has been done.
3. Git diff summary: run git diff main...HEAD --stat (or master...HEAD) to see what files changed.
4. Conversation context: review any tasks, plans, or discussion in the current session about what was built and why.
5. 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:

1. adr/content/adrs/ relative to the repo root
2. adrs/ relative to the repo root
3. adrs/ 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.