Documentation Review

Review documentation in the specified path (default: entire repository).

[!IMPORTANT] Consult REFERENCE.md in this skill directory for the expected output format and level of detail.

User Input

text

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Argument Parsing

Parse $ARGUMENTS for:

•Path: Optional path to review (default: repo root, reviews all docs)
•--create-beads: Create beads for findings (default: report only)

Workflow

•Run deterministic validation script for structural issues
•Find all README and CLAUDE.md files in scope
•Evaluate against quality criteria
•Cross-reference enumerations in docs against codebase sources of truth (see Enumeration Completeness)
•Check for existing beads: bd list --status=open
•For each issue found, skip if a bead already exists with matching file/issue
•Create beads only for new issues

Deterministic Validation

Before manual review, run the validation script for CLAUDE.md structural issues:

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/review-docs/scripts/validate-claude-md.py $0 --json

Parse the JSON output and include structural issues (missing tables, missing references, index drift) in your findings. The script checks:

•Presence of markdown tables with required columns
•Whether referenced files/directories exist
•Index drift (files not indexed, or index entries pointing to missing files)

Deduplication

Before creating a bead, check if one already exists:

•Run bd list --status=open to see all open issues
•Compare your findings against existing bead titles and descriptions
•Skip creating beads for issues that already have matching open beads
•When in doubt, show the user the potential duplicate rather than creating

Quality Criteria

Structure (Progressive Disclosure)

README.md files belong at component boundaries — the repo root plus the top-level directory of each major component (e.g., frontend/, backend/, infra/, docs/). Most subdirectories within a component should not have their own README. If a directory only needs a brief description and a pointer to its files, a CLAUDE.md index is sufficient.

Root README.md:

•Project purpose (why it exists)
•What it does (brief overview)
•Quick start instructions
•Links to component docs
•NO deep architectural details

Component READMEs (top-level component dirs only):

•Component's purpose in detail
•Architectural decisions
•Component-specific setup
•Internal APIs/interfaces

Do not flag missing READMEs in nested subdirectories (e.g., src/utils/, lib/internal/). Navigation within a component is handled by CLAUDE.md.

Content Quality

•Concise: No unnecessary words or redundancy
•Clear: Jargon explained, unambiguous
•Accurate: Examples work, paths exist, commands valid, lists reflect what actually exists in code
•Complete: Prerequisites listed, all steps included, enumerations cover all items (see Enumeration Completeness below)
•Consistent: Uniform terminology and formatting
•Internally consistent: Numbers, counts, and facts agree across all mentions within the same document

Content Quality applies primarily to README prose. For CLAUDE.md, focus on accuracy (index entries point to real files) and consistency (uniform table format).

Enumeration Completeness

When documentation contains a list of things — components, features, agents, services, environment variables, log files, database tables, API endpoints — verify the list is complete and accurate by cross-referencing the codebase.

Workflow:

•Identify every enumeration in the docs (any list that claims to describe "all" or "the" items of a type)
•Find the canonical source in code (e.g., config directory for agents, env template for env vars, schema definitions for DB tables)
•Diff the two: items in code but missing from docs, items in docs but removed from code
•Flag gaps as P3 (stale or incomplete)

Common patterns to cross-reference:

•Agent/service/component lists → config files or directory listings
•Feature/capability lists → tool, handler, or route files
•Environment variable documentation → .env.example, .env.template, or equivalent
•Log file lists → logging configuration entries
•Database table/schema documentation → schema definition files or migrations
•CLI command/Makefile target documentation → actual command definitions

What to skip: Exhaustive enumeration is not always expected. Use judgement — a "Key features" section need not list every minor capability. But a section titled "Agents" or "Configuration" that presents itself as comprehensive should be complete.

Hidden Knowledge

Good docs surface things newcomers can't discover on their own. Flag when these are missing:

Prerequisites & Environment:

•System dependencies (e.g., "requires Docker 20+", "needs libssl-dev on Linux")
•Required tool versions (node, python, go, etc.)
•Required accounts or API keys (with signup links, not the keys themselves)
•Environment variables with example values (use YOUR_API_KEY placeholders)

Platform Differences:

•OS-specific instructions when behavior differs (Mac vs Linux vs Windows)
•Architecture notes if relevant (ARM vs x86)

Gotchas & Failure Modes:

•Common setup errors and fixes ("If you see X, run Y")
•Non-obvious side effects ("This command also resets the database")
•Known limitations or unsupported scenarios

Magic Values:

•Default ports, timeouts, limits that aren't obvious from code
•Config file locations that vary by platform
•Implicit ordering dependencies ("Run A before B")

Quick Start Quality

The quick start should let someone succeed in minutes, not hours. Evaluate:

Copy-Pasteable Commands:

•Commands can be copied and run verbatim (no unexplained <placeholders>)
•If placeholders are needed, explain how to get the real value
•Shell-specific syntax noted if it matters (bash vs zsh vs fish)

Expected Output:

•Show what success looks like ("You should see: ...")
•Include sample output for key commands
•Note how to verify it worked

Minimal Path:

•Doesn't require reading other sections first
•Optional features clearly marked as optional
•"Hello world" possible before diving into configuration

First-Run Troubleshooting:

•Top 2-3 things that go wrong on first run
•One-liner fixes for each
•Link to more detailed troubleshooting if it exists

CLAUDE.md Navigation Index

CLAUDE.md files provide progressive disclosure via tabular indexes, pointing readers to the right file at the right time. README.md holds invisible knowledge (architecture, design decisions, invariants); CLAUDE.md holds navigation.

CLAUDE.md conventions inspired by solatis/claude-config (MIT).

Coverage — Non-trivial directories should have a CLAUDE.md. Skip generated dirs, vendored deps, stubs (.gitkeep only), .git, node_modules, __pycache__, dist, build, and similar.

Tabular index format — Each CLAUDE.md must contain at least one markdown table with columns: File (or Directory), What, When to read. Entries should use:

•Backtick-wrapped file/directory names (e.g., `src/`)
•Noun-based "What" descriptions (e.g., "Entry point", "Test utilities")
•Action-verb "When to read" triggers (e.g., "Adding a new route", "Debugging test failures")

Content separation (subdirectory CLAUDE.md only) — Subdirectory CLAUDE.md files should contain only:

•A one-sentence overview of the directory's purpose
•One or more tabular indexes

They should not contain architecture explanations, design decisions, invariants, or multi-paragraph prose. That content belongs in README.md.

Root CLAUDE.md operational sections — The root CLAUDE.md may additionally contain operational sections (Build, Test, Lint commands), agent instruction sections (e.g., beads workflow, tool configuration), and other project-wide guidance. This is expected and should not be flagged.

CLAUDE.md Progressive Disclosure

Detail belongs where the code lives. CLAUDE.md depth should match directory depth. The goal is to minimize context loading at each level — an AI working in internal/cloud/aws/ should not need to read the entire root CLAUDE.md to understand that directory.

The hierarchy works as follows:

•Root CLAUDE.md: Navigation index + dev commands. Just enough to find where to go.
•Branch CLAUDE.md (e.g., internal/cloud/): Architecture and patterns for that area + index to children.
•Leaf CLAUDE.md (e.g., internal/cloud/aws/): Implementation specifics for that directory.

Anti-pattern: A root CLAUDE.md that contains multi-paragraph explanations of how internal/cloud/ works, what patterns internal/broker/ uses, or how test/ is structured. That detail should live in the respective subdirectory CLAUDE.md files, not the root.

What root CLAUDE.md should contain:

•Project overview (1-2 sentences)
•Tabular navigation index pointing to major areas
•Build/test/lint commands
•Agent workflow instructions (if applicable)
•Common gotchas (brief, not exhaustive)

What root CLAUDE.md should NOT contain:

•Multi-paragraph architecture explanations for subdirectories
•Implementation patterns specific to a component
•Detailed testing approaches (belongs in test/CLAUDE.md)
•Provider-specific details (belongs in provider directories)

Index drift — Flag when:

•A file or subdirectory exists in the directory but is missing from the CLAUDE.md index (excluding dotfiles, generated artifacts, and files covered by glob patterns in the index)
•An index entry references a file or directory that does not exist
•A CLAUDE.md index links to a README that doesn't exist, or a README references a component whose CLAUDE.md is missing

Misplaced detail — Flag when:

•Root CLAUDE.md contains multi-paragraph explanations about subdirectory internals
•Architectural detail about a component appears in the root instead of that component's CLAUDE.md
•A branch directory lacks a CLAUDE.md but its detail is front-loaded in a parent CLAUDE.md

Checklist

Structure & Navigation

Content Quality

• No outdated references (paths, commands)
• Code examples syntactically correct
• Referenced files/commands exist
• Consistent terminology
• No duplicate information
• Numbers and facts consistent across all mentions within the same document

Codebase Consistency

• Enumerations (agents, features, env vars, etc.) cross-referenced against code
• No undocumented components in sections that present themselves as comprehensive
• No documented items that no longer exist in code

Hidden Knowledge

• Prerequisites documented (system deps, tool versions)
• Required env vars listed with example values
• Platform-specific instructions where behavior differs
• Common errors and fixes documented
• Magic values (ports, timeouts, defaults) explained

Quick Start

• Commands are copy-pasteable (no unexplained placeholders)
• Expected output shown for key steps
• Minimal path to first success (no detours)
• First-run troubleshooting for common failures

Output

You MUST produce a report following the exact structure shown in REFERENCE.md.

Severity guide:

•P1 — Security-relevant: docs omit auth steps, expose secrets in examples, or give dangerous command examples
•P2 — Broken: code examples that error, paths/commands that don't exist, quick start fails on copy-paste, index entries pointing to missing files
•P3 — Stale or incomplete: outdated references, missing prerequisites, missing env var docs, missing CLAUDE.md coverage, index drift, no expected output shown, misplaced detail (architecture in root instead of subdirectory CLAUDE.md), enumeration gaps (components/features/env vars in code but missing from docs), internal fact contradictions within the same document
•P4 — Polish: formatting inconsistencies, verbose wording, missing "When to read" triggers, missing platform-specific notes

--create-beads mode:

•

Errors/inconsistencies → bug beads:

bash

bd create --type=bug --priority=<1-3> --title="Docs: <issue>" --description="<file and explanation>"

•

Missing content → task beads:

bash

bd create --type=task --priority=<2-4> --title="Docs: <what to add>" --description="<what's needed and why>"