git:20260925.a3765d2 to git:20260926.538565e

---

name: adr-writer

description: Record a design decision as an Architecture Decision Record (ADR) in the project's `docs/adr/` directory. Use this skill whenever the user says "let's ADR this", "record this decision", "write an ADR for X", or when context-sync Phase 3 needs to extract a buried decision. The skill resolves the target ADR directory from cwd, picks the next sequence number with no collision, writes the 7-section body (incl. `Review-when` expiry conditions) in the main loop, runs the mechanical evidence and the adr-reviewer, and updates the ADR index. Also the canonical place for the filing bar — an ADR is written only for a mechanism / gate / threshold / agent-tier change that other artifacts cite, or for superseding / annotating a prior ADR; everything else goes into the commit body. Works across any repo — auto-detects or creates `docs/adr/` from the repo root.

user-invocable: true

origin: shimo4228

---

# ADR Writer

Capture a design decision as a numbered ADR with consistent structure. The skill handles the boilerplate (directory detection, sequence numbering, index update) in scripted steps, and the main loop writes the prose.

## Why the main loop writes

Deterministic concerns — where the ADR goes, what number it gets, which index needs updating — are easy to get wrong silently (number collisions, sub-directory cwd confusion, index drift), so they live in scripted steps. The prose is written by the main loop that holds the decision: rendering to the house template is cheap for it, and the decision packet (Step 3) is the discipline that keeps *decide* and *render* apart — the packet is settled first, the file is a faithful expression of it, nothing is inferred while writing. That principle is [ADR-0016](../../docs/adr/0016-writer-agents-render-not-decide.md) (writer agents render, they do not decide), applied in the main loop per [ADR-0072](../../docs/adr/0072-retire-adr-writer-agent-and-narrow-adr-filing.md); the evidence script (Step 4.5) is the fidelity check.

Write an ADR when at least one holds:

- The change moves a **mechanism, gate, threshold, or agent tier that other artifacts cite** (a hook, a lint boundary, a chain step, a rule's default, a model pin) — the ADR is what those artifacts point at

Entry points: the user says "let's ADR this" / "record this decision", `context-sync` Phase 3 surfaced a buried decision, a debate concluded and the outcome must outlive the session. Apply the two conditions to the request; when neither holds, say so and use the commit body.

## When NOT to Use — the commit body carries it

Everything else is recorded in the commit body, in three lines, so `git log --grep` finds it later:

```

Context: <what was observed, with its source>

Decision: <what changed, as a commitment>

Review-when: <the observation that would void it, or "none — record">

```

This covers bug fixes, reversible refactors, wording changes to rules / skills that nothing else cites, stocktake outcomes (retire / keep verdicts — the stocktake's own results file plus the commit), and personal preferences. When a commit-body decision later gets superseded or cited by another artifact, promote it: write the ADR then, quoting the commit.

## Workflow

### Step 1: Resolve the ADR directory

```bash

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT="$(pwd)"

ADR_DIR="$REPO_ROOT/docs/adr"

```

If `$ADR_DIR` does not exist, create it — the ADR request itself covers the directory, and

git makes it reversible. Mention the creation in your final report. Write a minimal

`README.md` index alongside:

````markdown

# Architecture Decision Records

## Index

| ADR | Title | Status | Date |

|-----|-------|--------|------|

## Template

ADRs in this repository use the 7-section template

(`scripts/adr_lint.py` checks section presence mechanically):

```markdown

# ADR-NNNN: [Title]

## Status

accepted | superseded | deprecated

## Date

YYYY-MM-DD

## Context

[what was the problem]

## Decision

[what was decided]

## Review-when

[expiry conditions — an ADR is a dated hypothesis, not a permanent constraint]

## Alternatives Considered

[rejected options and why]

## Consequences

[what becomes easier / harder]

```

File name: `NNNN-kebab-case-title.md` (zero-padded 4-digit sequence).

Index rows link the number: `| [NNNN](NNNN-slug.md) | Title | status | YYYY-MM-DD |`.

````

### Step 2: Pick the next sequence number

```bash

LAST_NUM=$(ls "$ADR_DIR"/[0-9]*-*.md 2>/dev/null | sort -V | tail -1 | sed -E 's|.*/([0-9]+)-.*|\1|')

if [ -z "$LAST_NUM" ]; then

NEXT_NUM="0001"

else

NEXT_NUM=$(printf "%04d" $((10#$LAST_NUM + 1)))

fi

```

Verify uniqueness right before writing (race safety):

```bash

[ -e "$ADR_DIR/$NEXT_NUM-"*.md ] && echo "COLLISION" || echo "OK"

```

If `COLLISION`, recompute `NEXT_NUM` from the latest state.

### Step 3: Gather the 7 inputs

Ask the user (or accept from caller) for:

1. **Title** — short, kebab-case-friendly (e.g., `context-sync-cascade-and-writer-agents`). The skill will compose the filename.

2. **Status** — `proposed | accepted | superseded | deprecated`. Default `accepted`.

3. **Context** — what problem prompted this decision (raw text OK).

4. **Decision** — what was decided (raw text OK).

7. **Consequences** — what becomes easier / harder (raw text or list).

If 3-7 are missing, request them — do not proceed. ADRs without these sections are noise.

**Assemble and approve the decision packet before writing.** Settle the actual content here: the real Context, the decision as decided, the Review-when triggers, why each Alternative was rejected (or under what condition it is revisited), which Consequences genuinely follow. Confirm this packet with the user (especially the Review-when, the rejection reasons and both sides of Consequences) *before* Step 4 — Step 4 expresses the packet and adds nothing, so a fuzzy decision is resolved here.

### Step 4: Write the file (main loop)

Read the 2 most recent ADRs in `$ADR_DIR` for house style (heading form, link style, whether

Consequences splits into Positive / Negative / Neutral), then write

`$ADR_DIR/$NEXT_NUM-<title>.md` from the Step 3 packet:

- Heading `# ADR-NNNN: <title>`, then the 7 sections in template order (Step 1's template, or

the repo's own `docs/adr/README.md` Template block when it differs)

- Every Context fact, Decision clause, rejection reason and Consequence comes from the packet.

Writing is expression, not synthesis — a consequence that feels "logically entailed" but is not

in the packet goes back to Step 3 for the user to approve, not into the file

- Links to sibling ADRs are relative (`./NNNN-slug.md`) and the file name is copied from `ls`,

not typed from memory — Step 4.5's `refs.links_broken` is the check

If a packet field is missing, stop and ask; do not write a partial ADR.

### Step 4.5: Run the mechanical lint and the per-ADR evidence

```bash

python3 ~/.claude/skills/adr-writer/scripts/adr_lint.py --root "$REPO_ROOT"

```

```bash

python3 ~/.claude/skills/adr-writer/scripts/adr_review_evidence.py --root "$REPO_ROOT" --adr "$NEXT_NUM" --diff worktree

```

### Step 4.6: Run the semantic review (adr-reviewer)

### Step 5: Update the index

After Step 4 writes the file, append a row to `$ADR_DIR/README.md` index table:

```bash

# Read current index

# Find the table block (lines between the "| ADR |" header and the next "##" heading)

# Append: | [$NEXT_NUM]($NEXT_NUM-<slug>.md) | <title human-readable> | <status> | <date> |

```

If the index table is malformed or absent, regenerate it from the directory:

```bash

for f in "$ADR_DIR"/[0-9]*-*.md; do

num=$(basename "$f" | sed -E 's|([0-9]+)-.*|\1|')

title=$(head -1 "$f" | sed -E 's|^# ADR-[0-9]+: ||')

status=$(awk '/^## Status/{getline; getline; print; exit}' "$f")

date=$(awk '/^## Date/{getline; getline; print; exit}' "$f")

echo "| [$num]($(basename "$f")) | $title | $status | $date |"

done

```

### Step 6: Report

Tell the user:

```

ADR written

---

File: docs/adr/<NNNN>-<title>.md

Number: <NNNN>

Status: <status>

Index: updated (+1 row)

```

## Edge cases

| Case | Handling |

|---|---|

| Called from a sub-directory of the repo | Use `git rev-parse --show-toplevel`; never trust raw cwd |

| Not a git repo | Fall back to cwd, warn the user that they should `git init` |

| ADR number was reserved verbally but not yet written ("I'll write ADR-0010 later") | Skill cannot know; ask the user whether to take the next free number or the reserved one |

| User wants to supersede an existing ADR | Update the old ADR's Status to `superseded by ADR-NNNN`, then create the new one. Two file writes. |

| Title contains spaces or non-ASCII | Skill normalizes to kebab-case ASCII for the filename; preserves original in the `# ADR-NNNN: ...` heading |

## Boundaries

- **Do not** invent missing sections. Refuse to write an ADR with `Context: [TBD]` or similar placeholders.

- **Do not** infer the user's decision from chat history without confirming. Ask, even if the answer feels obvious.

- **Do not** commit the file. The user owns the commit step.

## Reference Files

- ADR template canonical source: read the target repo's existing ADRs to mirror their voice. For the harness itself, see `~/.claude/docs/adr/README.md`.

- Evals: `evals/evals.json` (3 scenarios — new ADR / missing docs-adr / sequence collision).