Docs Checker

Docs Checker

Audit the repository's context files — CLAUDE.md at any depth, the .claude/ tree (skills, rules, commands), READMEs, and the docs tree — for correctness. This is a conservative audit: report findings with evidence, do not rewrite anything unless the user asks. Style, tone, and level of detail are the author's choices and are out of scope.

Prerequisites

• Node.js >= 22 (the bundled script uses fs.globSync)

Workflow

1. Deterministic pass

Run the bundled checker from the repo root:

node ${CLAUDE_SKILL_DIR}/scripts/docs-check.mjs $ARGUMENTS

It needs no config and no dependencies. What it does:

• Checks relative/absolute markdown links and image assets against the working tree
• Checks backticked source paths in prose (src/foo.ts, @alias/bar) against the codebase, resolving tsconfig/package.json aliases
• Scans the paths you name (or the repo's docs tree by default), plus every CLAUDE.md and the whole .claude/ tree automatically
• Cross-repo docs: pass --repo=NAME:DIR for each sibling checkout the docs reference

Exit 0 is clean, 1 means findings (printed as line:col rule message with did-you-mean hints), 2 is bad invocation. Its findings are ground truth — do not second-guess them.

2. Semantic pass

Read the context files the script scanned — but keep this pass on a scoped diet: CLAUDE.md files, the .claude/ tree, and top-level READMEs. Do not crawl the whole docs tree unless the user asked; the script already covered the wide surface.

Look only for claims you can verify against the repo right now:

• Commands or scripts quoted in docs that don't exist (check package.json scripts, Makefile, bundled scripts)
• Described behavior that contradicts the code it points at (read the code before claiming this)
• Instructions that contradict each other across context files
• Sections duplicated between files (e.g. README and CLAUDE.md drifting apart)
• References to tools, versions, or structures the repo no longer uses

Rules that keep this pass honest:

• Every finding must cite its evidence — the file and line that proves the claim stale. If you cannot point at proof, it is not a finding.
• No style or wording opinions. "Could be clearer" is not a finding.
• When unsure whether something is stale or intentional, list it under "unverified" rather than asserting it.

3. Report

Present one combined report:

1. Deterministic findings — the script output, summarized by file
2. Semantic findings — each as: claim, evidence (file:line on both sides), suggested resolution
3. Unverified observations — only if any; clearly separated

End with the totals. Do not edit any file. If findings exist, offer to fix them — deterministic findings (broken links, moved paths) are safe to fix mechanically once the user agrees; semantic findings need the user to decide the correct current truth first.

Suppressions

The script honors inline suppressions the user may already have in place:

• <!-- docs-check-ignore --> at the end of a line
• <!-- docs-check-disable --> … <!-- docs-check-enable --> around a region
• --no-agent-docs flag to skip CLAUDE.md/.claude/ scanning