# Check Docs

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

- Skill: `kunalsuri/check-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kunalsuri/check-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kunalsuri/check-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kunalsuri (https://skillmd.com/u/kunalsuri)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kunalsuri/check-docs

---

<!-- Copyright (c) 2026 Kunal Suri (CEA LIST). All rights reserved. -->

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