Decision History

Write one dated entry per design decision in docs/decision-history/. An entry records what was decided, why, and what was known on that day, in the past tense. The current design is the thing itself — rules, skills, hooks, tests, code — and the author's current instruction; an entry is read for the history behind it. A new decision may contradict an older entry; the older entry stays as written.

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 entry 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. A writer renders a decision; it does not make one. The evidence script (Step 4.5) is the fidelity check.

When to Use (filing conditions — canonical)

Write a new entry only when the decision meets all three:

• hard to reverse — undoing it means changing other artifacts (skills, rules, hooks, scripts) or public outputs too. Being revertible with git alone does not count as easy: nearly every harness change is git-revertible
• surprising without context — a future reader would ask "why is it like this?"
• the result of a real trade-off — chosen between genuine alternatives

"Hard to reverse" is met by most harness changes, so it mainly excludes changes whose effects stay local; "surprising" and "real trade-off" do the filtering.

A decision that changes or reverses an earlier entry is its own entry when it meets the three conditions. Link the earlier entry when it helps the reader (関連する経緯: [0035](./0035-slug.md)); the earlier entry keeps its text, its date and its state as written — the history stays readable in place, and git holds the order.

Entry points: the user says "record this decision" / "経緯を残して" / "ADR にして", context-sync Phase 3 surfaced a buried decision, a debate concluded and the outcome must outlive the session. Apply the three conditions to the request; when they do not all hold, 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 and why>
Review-when: <the observation that would reopen 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 cited by another artifact, promote it: write the entry then, quoting the commit.

Workflow

Step 1: Resolve the record directory

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT="$(pwd)"
if [ -d "$REPO_ROOT/docs/decision-history" ]; then DH_DIR="$REPO_ROOT/docs/decision-history"
elif [ -d "$REPO_ROOT/docs/adr" ]; then DH_DIR="$REPO_ROOT/docs/adr"   # repo that has not renamed yet
else DH_DIR="$REPO_ROOT/docs/decision-history"; fi

If $DH_DIR does not exist, create it — the request itself covers the directory, and git makes it reversible. Mention the creation in your final report. Write a minimal README.md index alongside:

# 判断の経緯（Decision History）

何を決め、なぜそうしたかの記録。1 件 1 ファイル、番号は連番、過去形で書く。現行の設計は実物と
今の指示が決め、記録は書かれた日の判断。新しい判断は旧記録と衝突してよく、旧記録はそのまま置く。

## Index

| # | Title | Date |
|---|-------|------|

## Template

Entries use the 6-section template
(`scripts/adr_lint.py` checks section presence mechanically):

```markdown
# NNNN: [Title]

## Date
YYYY-MM-DD

## Context
[what was the problem — facts of the day, with sources]

## Decision
[what was done and why — past tense]

## Review-when
[what observation would reopen this, 1–3 lines; or "none — record"]

## Alternatives Considered
[rejected options and why; a live rival as "Open — revisit when: …"]

## Consequences
[what became easier / harder]
```

File name: `NNNN-kebab-case-title.md` (zero-padded 4-digit sequence).
Index rows link the number: `| [NNNN](NNNN-slug.md) | Title | YYYY-MM-DD |`.

(Index rows make the number a relative link. adr_lint.py reads the expected section set from this README's Template fenced block, so placing the README doubles as the lint's template declaration. A repo whose README still carries the older 7-section template with ## Status is checked against that template until its README changes.)

Step 2: Pick the next sequence number

LAST_NUM=$(ls "$DH_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):

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

If COLLISION, recompute NEXT_NUM from the latest state.

Step 3: Gather the 6 inputs

Ask the user (or accept from caller) for:

1. Title — states the decision, kebab-case-friendly (e.g., context-sync-cascade-and-writer-agents). The skill composes the filename.
2. Context — what problem prompted this decision, with the facts and sources of the day (raw text OK).
3. Decision — what was done and why (raw text OK).
4. Review-when — what observation or premise failure would reopen this, 1-3 lines. It is a reservation of when to think again, captured at write time. If there genuinely is none, write "none — record".
5. Alternatives — what else was considered and why rejected, or, for an alternative that stays live, "Open — revisit when: …" (raw text or list). Keeping a rival open is allowed; a straw man is not.
6. Consequences — what became easier / harder (raw text or list).

If 2-6 are missing, request them — do not proceed. Entries without these sections are noise.

Preventive check (before settling the packet). Read references/review-findings.md (a dated casebook of frequent review findings) and self-check against the matching patterns — cited entries exist and say what is cited, provenance of coined terms, references to gitignored paths, sources and denominators of numbers, what is held fixed in count conditions. This is write-time prevention; semantic review is Step 4.6.

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. When your harness's boundary rule hands these records to the user, confirm this packet with them before Step 4; otherwise write it and show the packet in the report (the author's harness writes entries without confirmation — rules/common/boundary.md). 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 entries in $DH_DIR for house style (heading form, link style, whether Consequences splits into Positive / Negative / Neutral), then write $DH_DIR/$NEXT_NUM-<title>.md from the Step 3 packet:

• Heading # NNNN: <title>, then the 6 sections in template order (Step 1's template, or the repo's own README 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
• Decision in the past tense ("X を Y に移した", "moved X to Y because Z") — it says what was done and why; Review-when as observable triggers; each Alternative with its rejection reason or "Open — revisit when: …"
• Links to sibling entries 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
• When the decision went through a plan, the first line of Context links the approved plan: Plan: [docs/plans/<file>](../plans/<file>)（承認 YYYY-MM-DD）. The plan is the frozen precommitment; the entry still stands on its own — the link is provenance, not a substitute

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

Step 4.5: Run the mechanical lint and the per-entry evidence

python3 ${CLAUDE_PLUGIN_ROOT}/skills/decision-history/scripts/adr_lint.py --root "$REPO_ROOT"

Evidence mode (no verdict, exit 0). In the output JSON, fix the deviations in the entry you just wrote (missing_sections / case_mismatch / date / index / naming) before moving on. Deviations in existing entries are report-only — do not fix them in this step (separate task). The lint covers mechanical properties only and is not a substitute for semantic review (decision-history-reviewer).

When you want an ad hoc blocking verdict, add --gate. The exemption boundaries are unbounded by default, so pass per-repo values — harness uses --sections-from 44 --require-review-when-from 44 (exempting 0009's two missing sections and the absent Review-when in 0043 and earlier).

Next, take the per-entry evidence for the one you just wrote (the machine-countable part of the findings decision-history-reviewer repeats):

python3 ${CLAUDE_PLUGIN_ROOT}/skills/decision-history/scripts/adr_review_evidence.py --root "$REPO_ROOT" --adr "$NEXT_NUM" --diff worktree

Fix here what can be fixed at write time in the JSON — refs.unresolved (entry / RFC numbers that do not exist), refs.links_broken, missing (nonexistent paths) and ignored (gitignored evidence — promote it to docs/evidence/ or rewrite to be path-independent) in paths.flagged, paths.line_refs_out_of_range, numbers.percent_without_denominator, numbers.relative_referents (conversation references). If diff_scope.changed_not_mentioned lists changes the entry does not mention, write them into the Decision or split them into a separate commit. The remaining keys (numbers.unanchored, review_when, alternatives, consequences, second_record) need judgment and go to the Step 4.6 reviewer. relations.* is evidence of which earlier entries this one names; nothing in it asks for an edit to an earlier entry.

Step 4.6: Run the semantic review (decision-history-reviewer)

Before commit, launch agent: decision-history-reviewer and hand it the entry you just wrote — do not skip this. This skill is the only wiring for decision-history-reviewer — skipping it here means no semantic review runs at all. The main loop accepts or rejects each finding against the Step 3 packet, and fixes only the accepted ones.

Step 5: Update the index

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

# Read current index
# Find the table block (lines between the "| # |" header and the next "##" heading)
# Append: | [$NEXT_NUM]($NEXT_NUM-<slug>.md) | <title human-readable> | <date> |

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

for f in "$DH_DIR"/[0-9]*-*.md; do
  num=$(basename "$f" | sed -E 's|([0-9]+)-.*|\1|')
  title=$(head -1 "$f" | sed -E 's|^# (ADR-)?[0-9]+: ||')
  date=$(awk '/^## Date/{getline; getline; print; exit}' "$f")
  echo "| [$num]($(basename "$f")) | $title | $date |"
done

Step 6: Report

Tell the user:

Entry written
---
File:    docs/decision-history/<NNNN>-<title>.md
Number:  <NNNN>
Index:   updated (+1 row)

Edge cases

Boundaries

• The files this skill writes are the new entry and the index.
• The commit follows the repo's commit rule (the author's harness: rules/common/boundary.md).

Reference Files

• Template canonical source: read the target repo's existing entries to mirror their voice. For the harness itself, see ~/.claude/docs/decision-history/README.md.
• Mechanical lint (evidence mode + --gate): scripts/adr_lint.py (adapts the template automatically from the repo's record README Template; tests are tests/test_adr_lint.py).
• Per-entry review evidence (evidence mode only): scripts/adr_review_evidence.py ( cited references exist, path classification, diff scope, unsourced numbers; tests are tests/test_adr_review_evidence.py). This one file is the entry point for running and importing; the checks themselves are split across scripts/adr_evidence_common.py / _paths.py / _prose.py to stay within the per-file LOC budget.
• Casebook of frequent review findings: references/review-findings.md (read during the Step 3 preventive check).
• Evals: evals/evals.json (3 scenarios — new entry / missing directory / sequence collision).