sd0xdev/sd0x-dev-flow/adr
Claude Code and agent skill by sd0xdev/sd0x-dev-flow
- community
Checking that the SKILL.md file is still in the repository.
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).
Install
npx vskill@latest install sd0xdev/sd0x-dev-flow/adrSKILL.md
The same SKILL.md was published earlier as sd0xdev/sd0x-dev-flow/adr.
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
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.
(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):
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:
- Title — short, kebab-case (becomes the filename's
<title>segment) - Context — what forces are at play, what problem prompted the decision
- Decision — what was decided, stated as a decision, not a description
- Status —
ProposedorAccepted(defaultProposed; 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
- Consequences — what becomes easier or harder as a result, including negative tradeoffs
- 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.
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/adr/SKILL.md
Popularity
- Repository stars
- 188
- Repository forks
- 24
- 7-day trend score
- 26
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/sd0xdev/sd0x-dev-flow/adr)