| name | adr-scan |
| description | PROVISIONAL / one-off. Read-only full-repository scan that discovers ADR-worthy architectural decisions across the whole repo and maps each to the BACKLOG frame-ID taxonomy (Tier 0–6 / G,T,R,A,B,C,D). Unlike the go-boilerplate original (which migrated a flat decisions.md into docs/adr/), this repo already has a formal docs/adr/ set + BACKLOG.md board — so the job here is DISCOVERY of decisions that exist de-facto (in AGENTS.md, config files, src/ structure, .github/, code comments) but are NOT yet tracked as a BACKLOG frame, classifying each as decision (frame-worthy) / exclusion (frame-worthy negative decision) / rule (stays in AGENTS.md) / inventory (living reference), and proposing which Tier / frame ID it belongs to (existing or new). Read-only: produces a candidate inventory only; writes no docs/adr files and does not edit BACKLOG.md. Delete or archive once the discovered gaps are folded into BACKLOG.md. |
adr-scan (provisional)
Status: temporary / one-off. Built to sweep the repo for architectural decisions that are real but
untracked — deciding whether each deserves a slot on docs/adr/BACKLOG.md. Read-only: it emits a
candidate inventory only. It never writes docs/adr/**, never edits BACKLOG.md, never edits
source. Remove or archive it once the discovered gaps have been reconciled into the BACKLOG.
Why this exists here (differs from the go-boilerplate original)
The go-boilerplate version migrated a flat docs/decisions.md into a formal docs/adr/ set. This
repo is already past that: it has a formal ADR set (docs/adr/0001-* … Dev-000x … Toolchain-000x)
and a live board (docs/adr/BACKLOG.md) that tracks every decision area across Tiers 0–6 with
frame IDs (G / T / R / A / B / C / D) and a 選定済み / 実装済み status pair.
So the useful job here is gap discovery: find decisions that are being made de facto — encoded in
AGENTS.md, config files, the src/ layout, .github/, or code comments — but are not represented
by any BACKLOG frame (or are represented but mis-tiered / mis-classified). The output feeds the
BACKLOG運用ルール flow: 新しい意思決定領域に気付いたら該当 Tier への追加 → 内容合意 → ADR 化.
Classification taxonomy (the core judgment)
Each candidate is exactly one of:
- decision — a choice among alternatives with lasting consequences (X over Y). BACKLOG-frame-worthy.
- exclusion — a deliberate "we intentionally do NOT do X" with rationale. Frame-worthy (negative
decision; the BACKLOG "明示的に boilerplate では決めない (out of scope)" section is the home for some
of these).
- rule — a day-to-day constraint/consequence (e.g. "use the
@/* alias", "commit prefixes"). Stays
in AGENTS.md; may reference an ADR but is not itself a new decision area.
- inventory — a catalog that drifts with code (dependency list, script list). Stays in a living
reference doc / README, never an ADR.
A candidate is frame-worthy only if: it has (or implies) considered alternatives, it is cross-cutting or
hard to reverse, and it is not merely restating an existing rule/inventory or an already-tracked frame.
Scan surfaces (fan out one read-only worker each)
Fan these out in parallel via the Agent tool (read-only); each returns candidates in the output shape
below. Then the orchestrator dedups against the existing BACKLOG frames.
- Existing ADR + board —
docs/adr/*.md + docs/adr/BACKLOG.md. Build the baseline set of
already-tracked frames (so discoveries can be diffed against it). Note any ADR whose Status or
BACKLOG status pair looks inconsistent with reality.
- AGENTS.md — the
## [TODO] sections (each is a pending area — confirm it maps to a BACKLOG
frame), the "AI Modification Scope" / "Protected Documentation" / "Git Rules" / "Language Rules"
sections. Separate genuine decisions from rules.
- Config & tooling (latent decisions) —
package.json (deps, scripts, packageManager),
tsconfig.json, next.config.ts, biome.json, postcss.config.mjs, mise.toml, .makefiles/**,
.github/**. A pinned tool, an enabled compiler flag, a CI job, a browserslist — each may be a
decision made in config but never elevated to an ADR/frame.
src/ de-facto structure — the actual directory layout, "use client" placement, route
conventions, styling approach (Tailwind usage), any state/data-fetch pattern. These are the A-tier /
B-tier de-facto states; check each is reflected (as ⚠️ de-facto) in BACKLOG and not silently
hardening into an unrecorded convention.- Latent in prose/comments —
README*, code // TODO / // why comments, .github/copilot-instructions.md.
Decisions or exclusions stated in passing but never tracked.
Output (per candidate)
- title: short decision title (imperative, ADR-style)
type: decision | exclusion | rule | inventory
frame_worthy: yes | no
source: file:line (evidence)
alternatives: present | implied | none
backlog_state: tracked <frameID> | untracked | mis-tiered <current→proposed> | mis-classified
proposed_tier: Tier N + letter (e.g. "Tier 4 / B") — existing frame ID if one fits, else "new"
note: one line — why worthy / why not / what's inconsistent
Aggregate into:
- (A) Untracked decisions/exclusions — frame-worthy but absent from BACKLOG, with a proposed Tier +
frame ID. This is the primary deliverable.
- (B) Tracked-but-drifted — frames whose BACKLOG status pair (選定済み / 実装済み) or Tier looks wrong
vs the observed reality.
- (C) Stays-a-rule list — belongs in AGENTS.md, not a new frame.
- (D) Stays-inventory list — belongs in a living reference, never an ADR.
The orchestrator presents these to the user as candidates only. Folding any of them into
BACKLOG.md (or filing an ADR) is a separate, user-approved step — this skill does not perform it
(BACKLOG.md is AI-editable per CLAUDE.md, but the 運用ルール requires 内容合意 before a frame is added).
Constraints
- ✅ Read-only. Emit a candidate inventory only. Never write
docs/adr/**, never edit BACKLOG.md or
source, never file an ADR.
- ✅ Respect the Instruction Priority: AGENTS.md > ADRs > BACKLOG > agent configs. A "decision" that
contradicts an Accepted ADR is a finding, not something to normalize.
- ✅ Provisional: delete or archive this skill once the discovered gaps are reconciled into BACKLOG.md.
- ❌ Do not invent decisions to fill perceived gaps — only surface what has real evidence (file:line).
