Documentation Review

Structured documentation review producing actionable, prioritized findings with code-level references. Checks that documentation exists, is accurate, and stays in sync with the implementation.

Workflow

1. Scope and explore

• Confirm scope with the user: full codebase, specific packages/directories, changed files only (PR or branch diff), or specific concern.
• Resolve scope to a file/package list. Based on what the user requested:
  • Changed files (PR or branch): Run git diff --name-only --diff-filter=d <base>...HEAD to get changed files (default <base> is main). If the user references a PR number, use gh pr diff <number> --name-only instead. Filter to relevant file types (.go, .proto, .md, OpenAPI specs). Derive affected Go packages from the file paths (unique parent directories containing .go files).
  • Explicit paths/packages: The user may specify directories (e.g. internal/auth/), Go package patterns (e.g. ./internal/auth/...), or individual files. When given a directory or package pattern, include all files under it. Derive Go package paths for go doc invocations.
  • Full codebase: No filtering; explore everything (default).
• Pass the resolved scope (file list and derived package paths) to all exploration and investigation subagents so they only read and analyze scoped files.
• Detect which documentation surfaces exist within the resolved scope:
  • .go files → go doc analysis, doc.go files, Example* tests
  • .proto files → service/method/message/field comments
  • openapi.yml / openapi.yaml / swagger.* → API descriptions
  • *.md files → README, guides, changelogs

2. Launch investigation subagents in parallel

Launch up to 3 investigation subagents concurrently using the Task tool (model: sonnet per subagent-model-routing — documentation analysis requires cross-referencing signatures and prose). Each receives the list of in-scope files as context. Only launch subagents whose preconditions are met.

Future fan-out note: If per-symbol doc-comment presence checking is ever split into a dedicated fan-out subagent (e.g. one per package), use model: haiku per subagent-model-routing — presence checks are mechanical.

Every investigation subagent must check each finding against existing documentation: TODO comments, README notes, FIXME/HACK/XXX comments, and issue tracker references. Report tracked findings but mark them accordingly.

Subagent A: Go documentation (subagent_type="generalPurpose", requires .go files)

Prompt the subagent to:

• Enumerate packages: run go list ./... for full-codebase scope, or go list <package_paths> for the resolved package paths when scope is narrowed.
• For each package (sample if >20), run go doc -all <pkg> and inspect the output for:
  • Missing package-level comment (no doc.go or empty package doc).
  • Exported symbols (types, funcs, consts, vars) with missing or trivial (single-word, restating the name) doc comments.
  • Doc comments that don't start with the symbol name or don't end with a period.
  • Doc comment content that contradicts the actual function signature or behavior (parameter names, return types, error conditions).
• Check for Example* test functions in *_test.go files. Flag key exported APIs that lack examples.
• If go doc fails (e.g. build errors), fall back to reading doc.go and source files directly.
• Include a Tool Availability section noting whether go doc ran successfully.
• Return findings with DOC- prefixed IDs.

Subagent B: Proto and OpenAPI documentation (subagent_type="generalPurpose", requires .proto files)

Prompt the subagent to:

• Read all in-scope .proto files and check for:
  • Missing service-level comments.
  • Missing RPC method comments.
  • Missing or sparse message and field comments, especially fields with unclear names.
• Glob for openapi.yml, openapi.yaml, swagger.yml, swagger.yaml, or swagger.json files.
• If an OpenAPI spec exists, cross-reference against proto comments:
  • Proto comments should appear as description fields in the OpenAPI spec.
  • Flag drift: OpenAPI description empty despite proto comment existing, or content diverging.
  • Flag missing description on endpoints, request/response schemas, and parameters.
• Return findings with DOC- prefixed IDs.

Subagent C: Markdown and general docs (subagent_type="generalPurpose")

Prompt the subagent to:

• Glob for *.md files across the repo.
• Check README.md exists at the repo root. Flag if missing.
• Scan markdown files for:
  • Links to files that no longer exist (spot-check relative links against the file tree).
  • References to CLI flags, env vars, or config keys; spot-check a sample against actual code.
  • Code examples; spot-check function/type names against actual exports.
• Flag large documentation gaps: no README, no CONTRIBUTING guide (for OSS projects), no architectural overview for multi-service repos.
• Return findings with DOC- prefixed IDs.

3. Summarize

After all subagents complete, deduplicate overlapping findings, produce a consolidated table ordered by severity, and recommend fix order.

4. Present results

Resolve the review output directory:

REVIEW_DATE=$(date +%Y-%m-%d)
REVIEW_DIR="reviews/${REVIEW_DATE}"
if [ -d "$REVIEW_DIR" ]; then REVIEW_DIR="reviews/${REVIEW_DATE}-$(date +%H%M)"; fi
mkdir -p "$REVIEW_DIR"

Capture run metadata (see Run metadata header below) and prepend the rendered block to ${REVIEW_DIR}/DOCUMENTATION-REVIEW.md.

Write the output to ${REVIEW_DIR}/DOCUMENTATION-REVIEW.md, structured as:

1. Run metadata header
2. Tool availability summary
3. Consolidated findings table (with tracking status inline)
4. Recommended fix order

Present the report to the user.

---

Run metadata header

Capture once near REVIEW_DIR resolution and prepend the rendered block to the output document:

RUN_DATETIME=$(date -u +"%Y-%m-%d %H:%M UTC")
GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
GIT_COMMIT=$(git rev-parse --short HEAD)
GIT_COMMIT_FULL=$(git rev-parse HEAD)
GIT_SUBJECT=$(git log -1 --pretty=%s)
# When scope is diff-based, also: BASE_REF=<base>; BASE_COMMIT=$(git rev-parse --short "$BASE_REF")

Header template (placed at the top of the output .md, before the H1 title):

> **Run:** {RUN_DATETIME}
> **Branch:** {GIT_BRANCH} @ {GIT_COMMIT} (`{GIT_COMMIT_FULL}`)
> **Subject:** {GIT_SUBJECT}
> **Base:** {BASE_REF} @ {BASE_COMMIT}   <!-- omit when scope is not diff-based -->
> **Scope:** {scope description}

---

Finding link wrapping (PR mode)

When the review is scoped to a GitHub PR (pr_url is provided by the caller, or, when run standalone, gh pr view --json url -q .url 2>/dev/null returns one), wrap every path:line reference inside the finding tables below as a Markdown link:

~/.claude/scripts/pr-deeplink.sh "$pr_url" <path> <line>
# pr_url set   → [path:line](https://github.com/.../pull/N/files#diff-<hash>R<line>)
# pr_url empty → path:line   (plain text, unchanged)

The display text stays path:line so plain and linked tables look identical; only the URL goes in the link target. Pass L as the fourth argument for findings about removed code (default is R). Omit <line> for file-level findings to get a file-anchor link. Apply the same wrapping to path:line references inside the Tracked column (e.g. TODO in foo.go:42). Findings themselves follow terse-comments: concrete fix, optional bug:/risk:/nit:/unsure: prefix, no praise or restating the diff.

---

Output Templates

Per-category findings

| # | Finding | Severity | Tracked |
|---|---------|----------|---------|
| DOC1 | **Description.** Specific code reference (file:line or package). Explanation. | HIGH | — |
| DOC2 | Description with code reference. | MEDIUM | TODO in file:line |

Consolidated findings

| Severity | ID | Finding | Source | Tracked |
|----------|----|---------|--------|---------|
| HIGH | 1 | Description with code references | DOC1, DOC5 | — |
| MEDIUM | 2 | Description with code references | DOC3 | TODO in file:line |

Tracked column values: Use — for new findings. For already-captured findings: TODO in file:line, FIXME in file:line, README, #123 (issue reference), etc.

Re-evaluation table (for follow-up reviews)

| Finding | Status | What Changed |
|---------|--------|--------------|
| ~~1. Description~~ | FIXED | Brief explanation of the fix |
| 2. Description | Still applicable | No changes |

---

Guidelines

• Search the organization's codebase (Sourcegraph, GitHub) for existing documentation conventions before recommending changes.
• Include effort estimates to help prioritize implementation.
• When the user asks for a follow-up review, find the most recent review directory (ls -d reviews/*/ 2>/dev/null | sort | tail -1) containing DOCUMENTATION-REVIEW.md, re-evaluate all prior findings, and update with the re-evaluation table appended.
• For detailed documentation quality dimensions, see reference.md.
• REVIEW.md integration: If a REVIEW.md context section was provided by the review-all orchestrator (or exists at the repository root when running standalone), treat its rules as additional review criteria. "Always check" items are HIGH severity; "Skip" patterns exclude matching files from review scope.
• Findings must cite probed evidence (path:line, grep output, command result), not pattern-matched suspicion. Per ~/.claude/rules/probe-not-assume.md.