Adr

---
name: adr
description: "Write an Architecture Decision Record (ADR) for a feature — Context / Decision / Status / Consequences / Alternatives, filed as docs/features/<feature>/adr-<NNN>-<title>.md with a 3-digit zero-padded number. Handles the Superseded case: bidirectional linking when a new ADR replaces an old one. Use when: recording why an architectural approach was chosen, documenting a decision so it doesn't get re-litigated, marking a prior decision as superseded. Not for: feature-level technical design (use /tech-spec), task progress tracking (use /create-request), bulk backfill of historical decisions (a separate request — this skill writes one ADR at a time)."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(node:*), AskUserQuestion
---

# ADR — Architecture Decision Record

## Trigger

- Keywords: ADR, architecture decision record, decision record, record a decision, why did we choose, 架構決策, 決策紀錄

## When NOT to Use

| Scenario | Alternative |
|----------|------------|
| Feature-wide technical design (components, data flow) | `/tech-spec` |
| Task progress / acceptance-criteria tracking | `/create-request` |
| Bulk backfill of decisions already made in the past | Separate request — this skill writes one ADR per invocation, not a batch |

## Workflow

```
Phase 1: Resolve feature  → shared feature-context resolution
Phase 2: Compute number   → scan root + archived/, numeric max + 1, zero-pad to 3 digits
Phase 3: Gather content   → Context / Decision / Status / Consequences / Alternatives
Phase 4: Write ADR        → fill references/template.md, write to docs/features/<key>/
Phase 4b: Superseded link → (only if this ADR supersedes an existing one) edit both files
Phase 5: Report           → path written, number assigned, links updated
```

### Phase 1: Resolve Feature

Reuse the shared cascade — do not re-derive it here:
`@skills/create-request/references/feature-context-resolution.md` — the single copy since
doc-review-phasing r2 merged the two that had drifted apart; `/tech-spec` now keeps its own
command-free native-cascade reference in its own bundle instead of a second copy of this one —
canonical implementation `scripts/lib/feature-resolver.js`, invoked as
`node scripts/resolve-feature.js [--feature <key>]`.

**`scan_error` gate.** `scan_error !== false` ⇒ the source sets are **unknown, not empty** —
report it and take the ⚠️ Need Human exit rather than recording a decision against a corpus you could not read — an ADR is a
time-stamped claim about what was true, and one written from an unreadable corpus is wrong forever. Gate on `!== false`, not
`=== true`: a `{}` payload from a shell fallback carries no such field at all, and a non-null `key`
is not evidence the sets are complete — `scan_error` rides alongside a resolved key.

**The wrapper, not the CLI.** `resolve-feature.js` is the single owner of the failure payload: it
exits 0 and emits the full shape with `scan_error: true` however the CLI fails — nonzero exit,
signal, partial write, or a payload that is not the agreed shape; it cannot cover `node` itself
being missing, since nothing running under node can — where the CLI invoked
directly can die mid-write and a `|| echo '{}'` fallback of your own emits a payload with no
`scan_error` field at all. This skill briefly carried an exemption on the grounds that its
`allowed-tools` could not reach `bash`. The fix was not to widen the tool list but to make the
entrypoint reachable: `resolve-feature.js` runs under the `Bash(node:*)` this skill already grants,
so there is one failure contract and no exemptions, at no cost in permissions. (`Bash(node:*)` is
not universal either — `/codex-code-review` grants bash and no node, and keeps the shell shim. The
rule is that a skill instructs the entrypoint *it* is permitted to run.) This skill reads `key`,
`confidence` and `docs_path` only and consumes none of the four source sets, so the `scan_error`
gate the research skills carry does not bind it — but a `{}` reply still means the invocation failed
and is never an empty corpus.

**The gate below checks the directory (and the confidence), not `key` alone.** For Levels 1–3
(explicit `--feature` with a valid slug, branch `feat/<x>`, or a changed path under
`docs/features/<key>/`), `resolveFeatureContext` returns a non-null `key` with
`confidence: "high"` or `"medium"` even when `docs/features/<key>/` does not exist on disk — it
only probes the directory to enrich the result, never to invalidate it
(`scripts/lib/feature-resolver.js` § `probe`). An explicit `--feature` value that fails the
case-insensitive slug pattern (`/^[a-z0-9][a-z0-9._-]*$/i`, e.g. `--feature ../evil`) is rejected
at `scripts/lib/feature-resolver.js:13` before it ever reaches `key`. Level 3b (a changed path
under `skills/<key>/`, from line 140) only returns when `probe()` finds the directory; on a miss it falls through — to
Level 4 if `docs/features/` has **exactly one** subdirectory (returns that directory's name as
`key` anyway, `source: "single_dir"`, `confidence: "low"` — a guess, not a match on the actual
change), otherwise to Level 5 (`key: null`). the resolver prints the **full result
object** in the null case, e.g. `{"key":null,"source":"none",...}` — a bare `{}` means something
else entirely (no git root, or the CLI itself threw). A typo'd `--feature` value is the likelier
failure and does **not** produce a null key (Level 1 still returns it with `confidence: "high"`),
so gating on `key` alone silently creates a bogus feature directory instead of asking:

| Result | Action |
|--------|--------|
| `key` resolved, `confidence` is `"high"` or `"medium"`, **and** `docs/features/<key>/` exists | Continue to Phase 2 |
| `key` resolved but `docs/features/<key>/` does not exist (check with `node -e "process.exit(require('fs').existsSync(process.argv[1])?0:1)" "docs/features/<key>"` — this skill's `allowed-tools` has no general `Bash`, only `Bash(node:*)`) | **Gate: Need Human** — confirm this is really a new feature directory the user wants created; do not silently write into a typo'd path |
| `confidence` is `"low"` (`source: "single_dir"`) | **Gate: Need Human** — this is a guess ("only one feature directory exists"), not a match on the actual change; confirm it's the right one before writing into it |
| `key` is `null` (the resolver prints the full object, e.g. `{"key":null,"source":"none",...}`) | **Gate: Need Human** — ask which feature this ADR belongs to; do not guess |

### Phase 2: Compute the Number

Scan **both** the feature's root directory **and** its `archived/` subdirectory for existing
`adr-*.md` files. `rules/docs-numbering.md` § Ancillary docs defines the `adr-<number>-<title>.md`
filename pattern but says nothing about `archived/` — that convention lives in
`scripts/lib/doc-classifier.js` (`scanFeatureDocs`, which skips directories named `archived` at any
depth when building its *live* doc inventory). A number retired there is still taken, so this scan
is deliberately broader than that inventory — building the live-doc list and computing the next
free number are different purposes.

Run `skills/adr/scripts/next-adr-number.js` — do not hand-apply the max.
Numeric max, not lexical sort: string-sorting `adr-9-...` after `adr-10-...` would collide, which
is exactly the bug that shipping this as an unexecuted prose pin would miss.

```bash
node skills/adr/scripts/next-adr-number.js docs/features/<key>
```

(paths are repo-root relative, matching every other path in this skill). The function itself
(`nextAdrNumber`, exported for direct unit testing —
`test/skills/adr.test.js` exercises it against real temp directories, not just a prose pin):

```js
function nextAdrNumber(featureDir) {
  let max = 0;
  for (const dir of [featureDir, path.join(featureDir, 'archived')]) {
    let entries;
    try { entries = fs.readdirSync(dir); } catch { continue; }
    for (const name of entries) {
      const m = name.match(/^adr-(\d+)-/i);
      if (m) max = Math.max(max, parseInt(m[1], 10));
    }
  }
  return String(max + 1).padStart(3, '0');
}
```

The regex is case-insensitive (`/i`) — a hand-written `ADR-006-x.md` on a case-insensitive
filesystem still counts toward the max, avoiding a reissued number. The first ADR in a feature
(both directories empty or missing) produces `adr-001-<title>.md`.

### Phase 3: Gather Content

If not already supplied via `$ARGUMENTS`, ask for:

1. **Title** — short, kebab-case (becomes the filename's `<title>` segment)
2. **Context** — what forces are at play, what problem prompted the decision
3. **Decision** — what was decided, stated as a decision, not a description
4. **Status** — `Proposed` or `Accepted` (default `Proposed`; a *new* ADR is never created as
   `Superseded` — that value is only ever set on an *existing* ADR, by Phase 4b, on a later ADR
   superseding it). If the user states this ADR supersedes an existing one, ask which of the two
   the new ADR should carry — `Accepted` is the common case, but `Proposed` is valid too — then run
   Phase 4b after Phase 4
5. **Consequences** — what becomes easier or harder as a result, including negative tradeoffs
6. **Alternatives considered** — what else was on the table and why it lost

### Phase 4: Write the ADR

Fill `references/template.md` and write to
`docs/features/<key>/adr-<NNN>-<title>.md`. The **H1 must literally contain the string `ADR`**
(e.g. `# ADR-001: <Title>`) — `doc-taxonomy.json`'s `heading_signals` for the `adr` type is
`["Decision Record", "ADR", "架構決策"]`. For a well-formed `adr-<NNN>-<title>.md` filename,
`classifyByPath`'s `semantic_pattern` alone already reaches `medium` confidence, so the two signals
are not combined to jointly lift confidence — `doc-classifier.js` only consults `heading_signals`
when `scanFeatureDocs` is called with its `deep` option (not a CLI flag; the only production
caller, `scripts/lib/feature-resolver.js:29`, does not pass it, so this path is currently exercised
only by direct calls and tests), and only when `classifyByPath` already returned the fallback type.
Even then, a correct H1 is **necessary but not sufficient**: `classifyByHeading` lowercases the
first 20 lines and returns the *first* taxonomy type (in array order) whose signal appears anywhere
in them — ten types precede `adr` (index 10 in `doc-taxonomy.json`): the five lifecycle types plus
`review-log`, `fp-brief`, `tech-brief`, `checklist`, and `runbook`. The last two matter most here,
since they are two of the four the classification guard below defends against on the *filename* path
— an ADR about operational tooling plausibly has "runbook", "checklist", or "SOP" in its own
Context, misclassifying it on the *heading* path even with a perfect H1. This claim is pinned by a
test, not left as prose alone (`test/skills/adr.test.js` calls `classifyByHeading` directly), since
it depends on `doc-taxonomy.json`'s array order and would silently go stale on a reorder. The H1
requirement is worth keeping as a best-effort signal for the fallback case, not a guarantee.

Remove `references/template.md`'s two commented-out placeholder blocks (the `<!-- -->` slots
documenting where a future Supersedes/Superseded-by line goes) — unless Phase 4b runs in the same
pass, in which case replace the relevant one with the real line instead of deleting it blank.

**Classification guard — run before writing, not after.** `doc-taxonomy.json`'s type list is
checked in array order, and four types sit *before* `adr` (index 10) with patterns a free-text
`<title>` can actually hit: `checklist` and `runbook` carry **unanchored** substring patterns
(`^checklist-|確認事項|checklist`, `^runbook-|操作手冊|runbook` — the word anywhere in the filename
matches, e.g. `adr-002-runbook-automation.md`), and `fp-brief`/`tech-brief` carry **suffix**
patterns (`-fp-brief\.md$`, `-tech-brief\.md$`) that match if the title happens to end in that
phrase, e.g. `adr-003-vendor-tech-brief.md`. All four classify silently as that other type instead
of `adr`. `<title>` is free text from Phase 3, so this is reachable, not theoretical.

**Pass the bare filename only, never the full write path.** `classifyByPath` has no
`basename()` step and is path-sensitive: run it against the *full* target path
(`docs/features/<key>/adr-<NNN>-<title>.md`) and two independent things break — the leading
`docs/features/` segment defeats the `^adr-` anchor entirely (falls to the taxonomy fallback
type), and if `<key>` itself contains a colliding word (e.g. a feature directory named
`deploy-runbook`) the *directory* name — not the title — decides the result. The guard command
below strips to the basename itself with `path.basename()` so it gives the same, correct answer
whether the value passed happens to be the bare filename or the full path — verified both ways:

```bash
node -e "const {basename}=require('path'); console.log(require('./scripts/lib/doc-classifier').classifyByPath(basename(process.argv[1])).type)" \
  "adr-<NNN>-<title>.md"
```

If the printed type is not `adr`, do **not** write the file under that name. Ask the user to
rephrase the title to avoid the colliding word, recompute, and re-check — up to 3 attempts. Never
silently write a misclassified ADR; this is not the same failure as an unresolved feature, so it
does not route through the Phase 1 Gate: Need Human on the first miss — it is a title-collision
retry loop, not a missing-input one. After 3 failed rephrasings, stop retrying and escalate:
**Gate: Need Human** — a user who keeps proposing colliding titles is the case this bounds; the
`path.basename()` fix above already rules out the directory-name-collision case (the feature key
itself contains the colliding word), so this cap only needs to bound retitling attempts, not an
unfixable path.

### Phase 4b: Superseded Linking (only when this ADR replaces an existing one)

Bidirectional — both files change, in the same pass. Both edits target the `> **Status**` /
`> **Created**` blockquote at the top of `references/template.md` — never the `## Status` section
further down, which is a static legend explaining the three enum values, not a per-ADR value slot:

| File | Edit |
|------|------|
| New ADR (just written) | Add `> **Supersedes**: [adr-<OLD>](<path>)` as a new blockquote line, directly below `> **Created**` |
| Old ADR (existing file) | Change the existing `> **Status**: <value>` line to `> **Status**: Superseded`; add `> **Superseded by**: [adr-<NEW>](<path>)` as a new blockquote line below it. If the old ADR predates this skill and has no `> **Status**:` line at all, add one rather than assuming it exists |

`<path>` is relative to the file doing the linking, and the old ADR may resolve to either
directory found in Phase 2's scan — get this from wherever Phase 2 actually found the old number,
don't assume root:

| Old ADR found in | New ADR's `<path>` | Old ADR's own `<path>` (self-referencing the new one) |
|-------------------|---------------------|----------------------------------------------------------|
| feature root | `./adr-<OLD>-<old-title>.md` | `./adr-<NEW>-<new-title>.md` |
| `archived/` | `./archived/adr-<OLD>-<old-title>.md` | `../adr-<NEW>-<new-title>.md` |

If the old ADR named as superseded does not exist at either location, **Gate: Need Human** — do
not silently skip the link or guess a different file. If the old ADR is already `Superseded` by a
third ADR, **Gate: Need Human** — do not overwrite the existing link or append a second one.

### Phase 5: Report

Output the path written, the assigned number, and (if Phase 4b ran) both files touched with a
one-line diff summary of the added link.

## Numbering & Classification — Verification

- `adr-001-<title>.md` is the first-ADR filename shape (AC edge case)
- Number is a **numeric** max over `^adr-(\d+)-` (case-insensitive) across root + `archived/`,
  computed by `skills/adr/scripts/next-adr-number.js`, never hand-applied or a string sort
- `docs/features/<key>/adr-<NNN>-<title>.md` classifies via `doc-classifier.js`'s `semantic_pattern`
  (`^adr-|decision`) at step 4 — `medium` confidence, **not** the step-7 fallback type — **only when
  the title contains no word matching another type's pattern**; the Phase 4 classification guard
  exists because titles containing `runbook`, `checklist`, or ending in `-fp-brief`/`-tech-brief`
  demonstrably do not

## Output

- New ADR file at `docs/features/<feature>/adr-<NNN>-<title>.md`
- If superseding: the prior ADR file also modified (Status flip + Superseded-by link)

## Verification Checklist

- [ ] Filename matches `adr-<NNN>-<title>.md`, 3-digit zero-padded
- [ ] Number computed via `skills/adr/scripts/next-adr-number.js` (numeric max across root + `archived/`, not
      lexical sort, not hand-applied)
- [ ] Classification guard run before writing: `classifyByPath(filename).type === 'adr'`
- [ ] H1 heading contains `ADR`
- [ ] Template fields present: Context, Decision, Status, Consequences, Alternatives considered
- [ ] If Superseded: both the new and the old ADR cross-link, in the same pass, using the path
      table for whichever directory Phase 2 actually found the old ADR in
- [ ] No feature resolved → Gate: Need Human, not a guess

## After Creation

New to this feature's docs directory? Register it once via `/tech-spec` or `/create-request` so the
feature has a tech spec to link the ADR back to (`adr` is not one of `doc-classifier.js`'s
`canonical_roles`, so no tooling does this automatically) — an ADR with no owning tech spec is
still valid, just harder for a reader to trace to the feature's
broader design.

## References

- `rules/docs-numbering.md` § Ancillary docs — the `adr-<number>-<title>.md` pattern this skill implements
- `scripts/config/doc-taxonomy.json` — `adr` type entry (`ancillary` namespace, `semantic_pattern`, `heading_signals`); also where `runbook`/`checklist`'s unanchored patterns and `fp-brief`/`tech-brief`'s suffix patterns live, the reason for the Phase 4 classification guard
- `scripts/lib/doc-classifier.js` — `classifyByPath`, used by the Phase 4 classification guard
- `references/template.md` — the ADR template this skill fills
- `skills/adr/scripts/next-adr-number.js` — the numbering function Phase 2 runs, unit-tested directly by `test/skills/adr.test.js`

## Examples

```
Input: /adr --feature auth Title: Use JWT over session cookies
Action:
  1. Resolve feature → docs/features/auth/
  2. Scan root + archived/ for adr-* → none found → next number 001
  3. Gather Context/Decision/Status/Consequences/Alternatives
  4. Write docs/features/auth/adr-001-use-jwt-over-session-cookies.md
  5. Report: adr-001 written, Status: Proposed
```

```
Input: /adr --feature auth Title: Use opaque tokens (supersedes adr-001)
Action:
  1. Resolve feature → docs/features/auth/
  2. Scan root + archived/ → adr-001 exists → next number 002
  3. Gather content, Status: Accepted (this ADR), supersedes adr-001
  4. Write docs/features/auth/adr-002-use-opaque-tokens.md with "Supersedes: adr-001" line
  4b. Edit adr-001-use-jwt-over-session-cookies.md: Status → Superseded, add "Superseded by: adr-002" line
  5. Report: adr-002 written, adr-001 updated (Status + link)
```