| name | check-docs |
| description | Kit-maintainer diagnostic (LOCAL-ONLY, not distributed) that audits the README and docs/ for staleness against the repo's real command/skill/CLI roster, stamped tree, and cross-doc consistency. Read-only; produces a severity-ranked findings report. |
| disable-model-invocation | true |
Run the check-docs diagnostic. Read-only. Produce a structured findings
report; do NOT edit any file.
Local-only skill. This lives in .claude/skills/check-docs/ with no twin in
templates/, so the installer never stamps it into target repos. It audits
this kit's own README and docs — it is a maintainer tool, not a distributed
workflow. See .claude/LOCAL-ONLY-COMMANDS.md. (Its own file, and any
other local-only skill, is therefore expected to be absent from the
distributed roster — do not flag that as drift.)
Why this exists
Docs drift silently: a feature adds a command, a skill, or a stamped file, and
the prose roster, the What You Get tree, and the counts scattered across the
docs quietly fall behind the code. verify/drift//check-drift guard the
target-repo knowledge layer (ai/), not the kit's own public docs. This
skill closes that gap.
Ground truth — derive these FIRST, from the code, before reading any prose
The distributed reality is defined by templates/, not by .claude/
(which also holds local-only extras like this skill and /implement-spec).
Derive, deterministically:
- Distributed workflows = the sub-directories of
templates/claude/skills/ (the Claude surface — custom commands merged into
skills). This is the canonical "what users get" roster. Cross-check parity with
templates/github/prompts/, templates/agents/workflows/, and
templates/cursor/rules/ (a workflow is "universal" only if present in all).
- Distributed skills = the sub-directories of
templates/claude/skills/
and templates/agents/skills/.
- CLI commands = the members of the authoritative
const COMMANDS = new Set([…])
in install.mjs (the CLI's own routing source, also used by
test/release-check.mjs) — do not count command === "…" comparisons, which
also appear for sub-flows. Mirrored in the docs/CLI-REFERENCE.md "Command index" table.
- Stamped
ai/ tree = the structure under templates/ai/ plus the files
install.mjs writes directly (ai/repo-profile.json,
ai/install-manifest.json, optionally ai/repo-indepth.json).
- Local-only skills = present in
.claude/skills/ but absent from
templates/claude/skills/; the intended list is .claude/LOCAL-ONLY-COMMANDS.md.
Use ls/Glob and grep for these — do not eyeball. Every count you assert in a
finding must trace to one of these sources.
Docs in scope
README.md, docs/README.md, docs/FAQ.md, docs/MULTI-TOOL-SETUP.md,
docs/METHODOLOGY.md, docs/CLI-REFERENCE.md, docs/GETTING-STARTED.md,
docs/reports/technical-report-draft.md, and the root CLAUDE.md / AGENTS.md.
Checks
Section D — Command & skill roster
| ID | Check | Severity |
|---|
| D1 | Every prose count of workflows (e.g. README's "The Eleven Workflows" heading, "eleven workflows") equals the number of sub-directories in templates/claude/skills/ | ❌ |
| D2 | Every explicit workflow list/table (README roster table, MULTI-TOOL cross-tool table, technical-report §9.1) names exactly the sub-directories in templates/claude/skills/ — none missing, none removed | ❌ |
| D3 | Every skill reference (README tree + highlights, FAQ, MULTI-TOOL-SETUP, technical-report §9.3) matches the sub-dirs of templates/claude/skills/ / templates/agents/skills/ — no skill named that isn't shipped, none shipped that isn't named | ❌ |
| D4 | No local-only command (per .claude/LOCAL-ONLY-COMMANDS.md) is described anywhere as "stamped", "installed", or part of the distributed roster | ⚠️ |
Section E — CLI-command & stamped-tree drift
| ID | Check | Severity |
|---|
| E1 | Every "all N commands" claim (e.g. docs/README.md's CLI-REFERENCE blurb) equals the size of the COMMANDS set in install.mjs | ❌ |
| E2 | The docs/CLI-REFERENCE.md "Command index" table has one row per member of the COMMANDS set in install.mjs — none missing, none stale | ❌ |
| E3 | The README "What You Get" tree lists every path templates/ai/ stamps and every directly-written ai/ file (spot-check: START-HERE.html, INDEX.md, lab/WORKLOG.md, lab/reviews/, guide/*, analysis/*) | ❌ |
| E4 | The technical-report §8.1 directory tree agrees with the same stamped-tree ground truth | ⚠️ |
Section F — Cross-doc consistency
| ID | Check | Severity |
|---|
| F1 | The command / skill / CLI counts agree with each other across all in-scope docs (a number stated in two places must match) | ❌ |
| F2 | Version strings agree: package.json version vs the README citation version: vs CITATION.cff vs the newest CHANGELOG.md section | ⚠️ |
| F3 | No doc references a file, command, or stack that no longer exists (e.g. a removed install.py / Python path, a renamed command) | ⚠️ |
Section G — Path-claim resolution
| ID | Check | Severity |
|---|
| G1 | Every backtick-wrapped repo-relative path in the in-scope docs resolves on disk (same discipline verify applies to ai/, extended to README + docs/). Run node install.mjs verify . --strict first to clear the ai/ layer, then apply the path check to the docs above | ❌ |
| G2 | Every relative markdown link [text](path) in README.md and docs/README.md resolves on disk | ⚠️ |
Output format
Emit the report directly to the user (do NOT write a file). Use this structure:
check-docs — findings
══════════════════════════════════════════════════
Ground truth (from templates/ + install.mjs)
────────────────────────────────────────────
Workflow commands: <N> · Skills: <list> · CLI commands: <M>
Local-only (not distributed): <list>
Roster (Section D)
──────────────────
✅/⚠️/❌ <ID> <check name>
→ <where it's wrong>: <one-line concrete fix> ← omit for ✅
CLI & tree (Section E)
──────────────────────
✅/⚠️/❌ <ID> <check name>
→ <one-line concrete fix>
Cross-doc (Section F)
─────────────────────
✅/⚠️/❌ <ID> <check name>
→ <one-line concrete fix>
Path claims (Section G)
───────────────────────
✅/⚠️/❌ <ID> <check name>
→ <file:line>: <one-line concrete fix>
Summary
───────
X passed · Y warnings · Z errors
Next step: <single highest-priority action — one sentence>
Reporting discipline
- Report every check, not just failures — passing checks build confidence.
- For every ❌/⚠️, cite the exact file and, where possible, the line or
heading that is wrong, and give a concrete one-line fix — never just "this
is stale."
- When prose and code disagree, the code (
templates/ + install.mjs) is the
source of truth; the fix always adjusts the prose, never the code.
- The "Next step" names only the single highest-priority action.
What this command does NOT do
- Does not auto-edit any file — it diagnoses and reports only.
- Does not audit the target-repo
ai/ knowledge layer's file-path claims for
drift against source — that is verify / drift / /check-drift.
- Does not judge
ai/guide/ content quality — that is
/post-cold-start-verification / /verify-ai-readiness.
- Does not get distributed to target repos — it is local to this kit (see
.claude/LOCAL-ONLY-COMMANDS.md).
