Docs Consistency

Docs Review

Cross-cutting documentation review that checks consistency, accuracy, and completeness across the entire documentation ecosystem. It verifies that docs agree with each other and with reality; installed per-repository audit or sync workflows can deepen the check but are not required.

When to Use

• After adding, removing, or renaming skills, hooks, agents, or rules
• After major infrastructure changes (consolidation, new repos, renamed components)
• Before publishing or sharing the public repo
• Periodic health check (monthly)
• When the user says "review docs", "check my docs", "are my docs consistent"

When NOT to Use

• For per-repo prose quality — use an installed repository-documentation audit if available
• For mechanical count/freshness sync — use the repository's documented sync command
• For code architecture — use an installed external/code audit workflow

Argument Parsing

Parse $ARGUMENTS for scope (optional, default all):

Checks

Check 1: Count Consistency

Count actual components on disk, then verify every document that states counts matches reality.

Disk counts (source of truth):

Skills:  find skills -name SKILL.md -type f | wc -l   # recurse — skills/{engineering,research}/ are nested; ls -d skills/*/SKILL.md MISSES them (undercounts by ~5)
Hooks:   ls hooks/*.sh hooks/*.py hooks/*.mjs 2>/dev/null | wc -l   # hooks are .sh + .py + .mjs, NOT just .sh (counting .sh-only undercounts by ~15)
Agents:  ls .claude/agents/*.md | wc -l
Rules:   ls rules/*.md | wc -l

Counting gotchas (these caused false-positive drift reports on 2026-06-06): skills live in nested category dirs too (skills/engineering/, skills/research/) so you MUST find -name SKILL.md, not glob skills/*/; and hooks are written in shell, Python, and Node, so count all three extensions.

Documents to verify (private scope):

Documents to verify (public scope):

Report format per file:

| File | Component | Stated | Actual | Status |
|------|-----------|--------|--------|--------|
| README.md | Skills | 129 | 130 | MISMATCH |
| README.md | Hooks | 21 | 21 | OK |

Check 2: Component Coverage

Every component on disk must appear in its catalogue file. Every entry in the catalogue must exist on disk.

For each: list items on disk not in catalogue (undocumented) and items in catalogue not on disk (orphan entries).

Also check README.md skill category table — every skill on disk should appear in exactly one category row.

Check 3: Stale References

Grep documentation files for references to components that no longer exist on disk.

Scan these files:

• README.md, CLAUDE.md
• docs/*.md (all)
• the user-manual .tex source (in docs/reference/user-manual)
• skills/shared/*.md
• rules/*.md

What to look for:

• Skill names (/skill-name or backtick-quoted) that don't match any skill on disk — resolve via find skills -name SKILL.md (a name like skill-latex is the MCP-tool form of the latex skill, NOT a separate/orphan skill — strip the skill- prefix before checking)
• Hook script names that don't match any hooks/*.{sh,py,mjs} file
• Agent names that don't match any .claude/agents/*.md file
• Broken relative links (markdown [text](path) where path doesn't exist)

Exclude log/ and MEMORY.md — these are historical records, not active documentation.

Check 4: Public-Private Cross-Consistency

Verify that public and private docs agree on the same facts.

1. Count alignment: Compare counts in public/public-repo/README.md vs README.md. They should match (sync-to-public.sh propagates counts).

2. Section currency: For each synced section (Architecture, Workflows, Session Continuity, Design Principles, Credits), check that the public version matches what extract_section() would produce from the private README. Flag sections where content has diverged.

3. Marker freshness: Check auto-generated markers in public README (COMPONENT-TABLE, SKILLS-SUMMARY, AGENTS-TABLE, HOOKS-TABLE, RULES-TABLE, FILE-TREE, FILE-STRUCTURE). Run uv run python scripts/generate-public-docs.py --dry-run if available, or manually compare marker content against disk reality.

4. Leaked details: Grep public repo for personal details that should have been anonymised:

   • Institutional names (your affiliations) outside of credits/attribution
   • Personal names (other than in credits)
   • vault file paths
   • GitHub usernames (other than user in attribution)