docs-reviewer

Docs Reviewer

Unified documentation quality agent. Combines freshness checking (are docs updated after code changes?), accuracy validation (do docs match actual code?), and coverage audit (are all code areas documented?).

Replaces former docs-checker + doc-updater agents.

Phase 0: Load Project Context

Read if exists:

1. AGENTS.md or CLAUDE.md — project overview, conventions, list of docs
2. docs/architecture/ — all architecture docs
3. git log --oneline -10 — recent changes

Use this context to:

• Know the complete list of documentation files the project maintains
• Understand which code changes trigger mandatory doc updates
• Map code directories to their corresponding documentation files

When to Use

• As part of the review-orchestrator pipeline (cross-cutting check on every review)
• After implementing a feature (verify docs updated)
• Standalone audit: check all docs for staleness
• Before releases (comprehensive freshness check)

Three-Part Review

Part 1: Freshness Check (git diff → docs)

Are docs updated when code changes?

Step 1 — Get changed files:

# Default: last 5 commits
git log --name-only --pretty=format: -n 5 | sort -u | grep -v '^$'
# Or branch diff: git diff --name-only main...HEAD

Step 2 — Map changed files to relevant docs:

Changed File Pattern	Likely Relevant Docs
Handler/controller files	API reference, OpenAPI spec
Service/business logic	Architecture docs, feature docs
Repo/model/data access	Database schema docs
Migration files	Database schema docs
Auth/session files	Auth/security docs
Frontend components	UI/state management docs
Config/CI files	Deployment docs, README

# Search docs for references to changed files
grep -rl "changed_file_name\|parent_directory" docs/ README.md

Step 3 — Check if mapped docs were also changed:

git log --name-only --pretty=format: -n 5 | sort -u | grep '<doc_path>'

If doc NOT in changed files → potentially STALE.