docs-check

Check Documentation Quality

Audit documentation freshness, completeness, and quality against the current codebase state. Read-only: never edit or write to any doc file.

Anti-Hallucination Detection

This skill exists to catch docs that lie. For every claim in a doc, verify it against the actual codebase rather than trusting the doc text:

1. Cross-reference claims: component/service names, described relationships
2. Verify counts: if a doc says "5 services", count the actual services
3. Check file references: confirm every referenced path exists
4. Validate diagrams: every Mermaid entity must exist in real code

Workflow

Phase 1: Scan docs/

1. Glob all documentation files (docs/, docs/adr/, docs/rfc/, top-level README.md, CONTRIBUTING.md).
2. Infer focus categories from the filenames actually present: don't assume a fixed set. A repo with docs/data-model.md gets a "data" category; one with docs/deployment.md and docs/docker-compose.yml docs gets "infrastructure"; group whatever's there under a name that matches its content. If the user names a focus that doesn't match anything found, say so and list the categories that do exist instead of silently no-op'ing.
3. Detect tech stack, database presence, deployment configs, and project type from the codebase (package files, Dockerfiles, etc.) to know what documentation should exist.

Phase 2: Parse arguments

Extract an optional focus keyword from the invocation and match it against the categories found in Phase 1. No argument means check everything found.

Phase 3: Verify claims against the codebase

For a small doc set (a handful of files, or a one-shot check like "does this file exist"), verify directly inline with Read/Grep/Glob/git: spawning a subagent for a single lookup adds latency for no benefit.

For a large multi-doc audit (a full docs/ tree, many ADRs, cross-referencing several files against the codebase), spawn one Explore subagent per document or logical section so each verifies its claims independently. Where no Task tool is available, fall back to processing each document sequentially inline instead: same verification steps, one document at a time, no parallelism. See references/verification-patterns.md for section-level verification patterns and bash commands.