Adr

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:

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:

<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:

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)