verify-docs

name	verify-docs
description	Verify documentation claims against actual code, finding and fixing stale or incorrect docs. Audit docs for token efficiency — cut what strong LLMs already know, keep local specifics and gotchas. Use when asked to review docs, trim docs, or check docs are accurate.

Verify and Optimize Documentation

Audit repo documentation for correctness and token efficiency.

Principles

Docs are primarily consumed by LLM agents. Strong LLMs already know standard languages, frameworks, well-known APIs, and general SE practices. Only document:

• Local specifics: bespoke APIs, repo-specific patterns, non-obvious config
• Gotchas: things that previously broke, counterintuitive behavior
• Deviations: where this repo does something non-standard

Cut everything a strong LLM could derive from reading the code or from general knowledge.

Standards

• AGENTS.md: open standard for AI coding agent instructions. Spec: https://agents.md/, repo: https://github.com/agentsmd/agents.md. Agents read the nearest AGENTS.md in the directory tree; monorepos use per-package files.
• CLAUDE.md: Claude Code's equivalent. Claude reads CLAUDE.md files hierarchically — all parents from repo root to current directory are loaded into context. Docs: https://code.claude.com/docs/en/memory
• @-transclusion: Claude Code feature where @path/to/file on its own line imports that file's content. Paths resolve relative to the importing file. Max depth: 5 hops.

Audit procedure

1. Discover conventions: read root AGENTS.md, STYLE.md, README.md to learn this repo's doc structure, file hierarchy, and naming conventions. Don't assume — each repo may differ.
2. Inventory: find all documentation files (markdown, plaintext, in-code docs).
3. Structural check: verify the repo's own doc conventions are followed consistently.
4. Staleness check: for each claim in docs (file paths, function signatures, env vars, CLI flags, build targets), grep the codebase to verify it still exists and is accurate. Flag stale references.
5. Token audit: for each doc, flag:
   • General knowledge LLMs already have
   • Restated type signatures or parameter lists
   • Explanatory prose that doesn't add info beyond what the code shows
   • Redundant examples (one is enough per pattern)
   • Content duplicated between parent and child docs
   • Repo conventions restated in sub-docs that inherit from parent
6. Classify kept content: confirm remaining content falls into: local specifics, gotchas, deviations, bespoke API details, or recovery procedures for past failures.
7. Propose changes: present a concrete diff or list of cuts with rationale. Group by file.

What to cut (examples)

• General framework knowledge ("pytest uses fixtures for shared setup")
• Standard library explanations (what pathlib.Path is)
• Obvious build/test commands (bazel test //path:target)
• Lengthy examples of standard patterns
• Style rules that restate language conventions (PEP 257, etc.)

What to keep (examples)

• Non-obvious gotchas that caused real failures
• Bespoke API details not widely known
• Recovery procedures for past outages
• Repo-specific macros, entry points, or tooling
• Policy decisions that could go either way

Prefer references over inline context

Reference external sources rather than restating them. Prescribe agents to fetch context on demand (WebFetch a URL, invoke a skill, read a file) instead of embedding the full content. This keeps docs small and avoids staleness.

Structural improvements

• Historical/stale docs should be clearly marked — by convention, filename, banner, or directory placement (e.g., archive/). The mechanism doesn't matter; what matters is that agents can tell current docs from historical ones.
• Verify link targets: check all internal links actually resolve. Common issues: hyphens vs underscores, missing subdirectories, renamed files.
• Cohesive flow over cumulative patches: docs that grew by accretion should be restructured into logical sections. Group related content; don't just append. Choose an internal structure appropriate to the doc type — e.g., investigation notes: summary → timeline → diagnostics → root cause → fix. Decision docs: problem statement → requirements → options considered → decision. Don't force a single template; pick what fits.
• Structural reshuffling: when a doc is too large (>200 lines), consider splitting into focused sub-docs. When multiple small docs overlap, merge them. Rename/move files to better locations when the current placement is confusing. Extract reusable sub-docs that multiple parents can reference. The goal is docs that are cohesive, focused, and easy to navigate — not accumulated patches.