review-docs

What this skill does

# Documentation Review

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

> [!IMPORTANT]
> Consult [REFERENCE.md](REFERENCE.md) for the expected output format and level of detail.

## Scope

Determine the review scope before discovering files:

- If `$ARGUMENTS` is non-empty, treat it as a path (file or directory) and run:
  ```bash
  ${CLAUDE_PLUGIN_ROOT}/scripts/discover-files.sh "$ARGUMENTS"
  ```
- If `$ARGUMENTS` is empty, scope to files added or modified on the current branch relative to the default branch:
  ```bash
  ${CLAUDE_PLUGIN_ROOT}/scripts/discover-files.sh
  ```

Handle the script's exit codes:
- **0 with output** — use the listed paths as input to the discovery step below.
- **0 with empty output** — branch has no diff vs the default branch. Tell the user and ask which path to review.
- **non-zero** — script prints a message to stderr (path not found, not a git repo, on the default branch with no path, detached HEAD, or default branch indeterminate). Relay the message and ask the user which path to review.

The script returns paths language-blind. The discovery step below filters to README.md and CLAUDE.md files; this filter is universal across languages so a fallback is rarely needed.

## Workflow

1. Run deterministic validation script for structural issues (always repo-wide — structural drift outside the branch scope still matters)
2. Find README and CLAUDE.md files in the script's output
3. Evaluate against quality criteria
4. Cross-reference enumerations in docs against codebase sources of truth (see Enumeration Completeness)
5. Produce the findings report

### Deterministic Validation

Before manual review, run the validation script for CLAUDE.md structural issues. Pass the repo root so structural problems anywhere in the repo are caught regardless of branch scope:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/review-docs/scripts/validate-claude-md.py . --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)
- `@path` import targets resolve to existing files
- `.claude/rules/` file structure, frontmatter globs, and empty files
- Leaked local preferences (hardcoded user paths, localhost URLs) in shared CLAUDE.md

## 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**:
1. Identify every enumeration in the docs (any list that claims to describe "all" or "the" items of a type)
2. Find the canonical source in code (e.g., config directory for agents, env template for env vars, schema definitions for DB tables)
3. Diff the two: items in code but missing from docs, items in docs but removed from code
4. 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. Also skip `CLAUDE.local.md` and `MEMORY.md` — these are personal/auto-managed and not part of shared project documentation.

**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:
- Backti