review-docs

name	review-docs
description	Multi-agent review of user-facing docs (README, docs/**, --help text) for simplicity and correctness. Use before any release, after any feature PR that touched docs, or when asked to review docs.
trigger	/review-docs

/review-docs — the docs panel (group review, two lenses)

Docs are product surface. This skill runs at least two independent agent reviewers in separate contexts — never one agent wearing both hats, never the agent that wrote the docs — then consolidates findings and applies fixes.

Reviewer A — the cold reader (simplicity)

Prompt an agent that has NEVER seen this repo: it gets README.md (and only what the README links) and must, in order: (1) say in one sentence what the tool does; (2) run the quickstart commands verbatim against a fixture; (3) flag every place it stumbled — jargon, missing steps, buried assumptions, anything it had to guess. Length findings count: a section a cold reader skips is a section to cut. Deliverable: stumble list + the one-sentence comprehension check.

Reviewer B — the correctness auditor

A separate agent (different context; Codex preferred — different model family) audits every claim against the code:

• Every command/flag in README, docs/**, and --help exists and runs with exit 0 on a fixture (execute them — don't eyeball).
• Every factual claim maps to code (file:line) or a test; overclaims are findings (I3: docs never promise more than the code does — "never/always/zero" claims get special scrutiny).
• Parity surfaces verified: docs/telemetry.md ↔ zod schemas (the SPEC-0002 test), docs/json-schema.md ↔ schema when it exists, help text ↔ args.ts.
• Stale references: renamed flags, removed commands, dead links, version drift.

Consolidate, fix, record

Merge both lists, dedupe, apply the accepted fixes (docs edits are cheap — default to fixing, not filing), note rejected findings with one-line reasons. Record the panel's verdict (reviewers, findings count, fixes applied) in the PR or release notes. Docs review is BLOCKING for a release; advisory-but-expected for feature PRs.