Review Docs Playbook

Read principles.md first, then apply this checklist.

1. Scope and classification

Identify doc type and target audience.
Confirm brownfield vs evergreen intent.
Confirm expected outcome for the reader.
For full-repo reviews, explicitly include both governance surfaces and product-doc surfaces (docs/, README trees, .md/.mdx/.mdc, .rst/.rsc, framework docs configs).
For OpenClaw docs reviews, apply references/openclaw.md for page type, docs IA, preservation, examples, and validation checks.

Proactively find issues and risks without waiting for repeated prompts.
If there are signals of deeper problems, continue investigation beyond the first pass.
Long-running and extensive investigations are acceptable when needed for confidence and correctness.
When available, use sub-agents for bounded parallel discovery (for example file-inventory, command validation, or cross-doc consistency checks), then merge to one final issue set.
When no issues are found, state that explicitly and call out residual risks or validation gaps.
Default to apply-fixes for high-confidence documentation defects unless the user explicitly requests report-only.
Do not stop at AGENTS/CONTRIBUTING checks when the task is documentation-wide; continue into docs-content and docs-framework surfaces.

Use references/agent-and-contributing.md as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling. For AGENTS.md:
confirm persona intent, scope, and command/tool boundaries are explicit.
check frontmatter style matches repo conventions when present.
ensure Always, Ask first, and Never boundaries are present when expected.
require concrete command examples and repo-specific paths to avoid ambiguity.

For CONTRIBUTING.md:

verify issue/PR workflow is complete and actionable.
ensure local setup, lint/test commands, and review criteria are accurate.
ensure governance does not conflict with nested AGENTS instructions.
flag oversized files that should be split into linked section docs (for example tool-specific setup and release docs).

For agent-platform awareness:

confirm references are minimal and scoped for Cursor/Claude glob behavior.
confirm Codex-facing guidance uses explicit file references.
confirm both surfaces represent the same shared policy core (commands, boundaries, and precedence), not divergent guidance.
audit .agents/.cursor compatibility behavior:
- verify canonical rule directory and symlink state match repo policy
- verify symlink target integrity and platform/tooling expectations
- verify AGENTS policy references remain canonical for Codex even when .cursor compatibility exists
check for context bloat from duplicated policy statements across agent and contributor files.
check for conflicting rules, skills and agent instructions
check for conflicting information in agent instructions vs codebase
check for broken or missing referenced files (for example README/index files named as canonical entry points).
check for setup/command drift (for example non-existent install commands, root-level commands that should be module-scoped).

Verify docs IA coverage across root/module README* files and docs/** trees.
Review framework-native docs sources in scope (for example Fern, Mintlify, Sphinx, MkDocs) and ensure guidance matches actual source-of-truth files.
Check .md/.mdx/.mdc/.rst/.rsc for stale commands, missing prerequisites, and broken cross-links.
Confirm referenced doc paths and anchors exist.
Flag docs that should be split/merged to improve discoverability and maintenance.
For OpenClaw docs, check docs/docs.json, docs-list routing hints, main path versus Reference placement, and generated-reference visibility.
For OpenClaw rewrites or page splits, require source-backed keep/drop/move/destination coverage for important claims, warnings, examples, commands, fields, and troubleshooting facts.

Detect and read framework config first (for example Fern config, Sphinx conf.py, Mintlify config, or equivalent).
Resolve path references relative to the declaring file/config.
Treat filesystem paths and published URL routes as separate maps; verify both.
Flag path-map drift explicitly (missing file, stale route, wrong base path).

Funnel check: what/why, quickstart, next steps.
Validate heading flow and navigation discoverability.
Flag critical content trapped in images or buried sections.
Check Diataxis alignment and split mixed-purpose sections.
For OpenClaw docs, confirm the content matches an explicit page type from references/openclaw.md.

Read tooling.md if platform fit is uncertain.

Confirm declared source-of-truth language and expected parity policy.
Compare changed sections across locales for step/order/warning drift.
Flag missing updates to prerequisites, version notes, limits, and safety guidance.
Allow intentional divergence only when rationale is explicit and user-impact is low.
Require a reader-visible status note when locale parity is partial.