adr

Files (3)

• SKILL.md
• template.md · references/
• next-adr-number.js · scripts/

SKILL.md (first lines)

# 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`.

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness