Review Docs

---
name: review-docs
description: >-
  Adversarially review documentation: verify every claim against the current code,
  run the examples, and check it serves its reader. Use when reviewing a README,
  guide, reference, or doc change, or after a code change that touched user-facing
  docs. Do NOT use for writing/updating docs (use write-docs) or reviewing code logic
  (use review-code).
reviewed-against: "0.43"
category: assurance
evidence-profile:
  - review-result
---

# review-docs

Stale docs are worse than no docs — they actively mislead. Review the docs the same
way review-code treats code: verify against reality, severity-tag findings, don't
approve on "looks fine".

## ACCURACY — highest priority
- [ ] Check every claim against the **current code**: signatures, parameters, return
      values, flags, errors, config keys, defaults, output, and version numbers must
      match what the code does **today**. Flag any drift as **BLOCKING** — a confidently
      wrong doc is worse than a missing one.
- [ ] In a **design or specification document**, proposals are allowed: check that
      anything not built yet is clearly labelled (a `Status: proposed` line, "will" /
      "proposed" wording) and that what it says about today's behavior matches the
      code. An unimplemented proposal presented as existing behavior is **BLOCKING**.
- [ ] **Run every example / command / snippet of existing behavior** (or confirm CI runs
      them) and confirm the documented result. Reject illustrative-but-unrun examples
      that "should work".
- [ ] In a `Status: proposed` design or specification, an example of a proposed command,
      API or setting cannot run yet: check it against the proposed contract instead, and
      check that it is visibly marked (for example "proposed, not runnable yet"). Never
      require an implementation just to approve a design.

## FIT & COMPLETENESS
- [ ] **Mode check** — the page is a single clean Diataxis mode (tutorial / how-to /
      reference / explanation), not a hybrid that half-teaches and half-references. A
      design or specification document counts as explanation mode and may hold
      requirements and alternatives.
- [ ] **Audience & goal** — clear and consistent; the content serves that reader.
- [ ] **Completeness for the stated task** — no missing step, prerequisite, edge case,
      or error path a real user would hit.
- [ ] **Clarity & scannability** — scannable structure, descriptive headings, concise
      sentences, descriptive link text, code in code font.
- [ ] **Voice** (../_shared/references/plain-language.md, kind B) — the document opens
      with an "In plain words" summary and its plain words are true for this case;
      reference material keeps exact names, flags and fields, explained the first time.
      Voice findings (a missing summary or unexplained jargon, each minor): raise them
      for a document that is new or changed in the work under review, and for any
      document when someone asks for a voice, prose or audience review of it. Skip
      them only for a document you meet incidentally while reviewing an unrelated
      change; untouched documents are not rewritten just for voice. A plain paraphrase
      that changes a fact is an accuracy finding (blocking) in any document.

## DRIFT GUARDS
- [ ] No stale screenshots, paths, env-var names, command flags, or output blocks.
- [ ] No broken links or dead anchors (run / confirm the link checker).
- [ ] Changelog / navigation / API reference updated to match the change.

## REPORT
- [ ] Severity-tag findings `[blocker] / [major] / [minor] / [nit]` like review-code;
      blockers = inaccuracies and broken examples.
- [ ] Confirm the docs-as-code CI gates (markdownlint / prose linter / link check)
      actually **ran** for the changed files — do not approve on green-but-skipped checks.

## Evidence

Emit the `review-result` profile (full rules + bus-validated vs skill-policy: ../_shared/references/evidence.md).

Required fields:

- `risk_class`
- `release_blocker`
- `tests_referenced`
- `tests_executed`
- `residual_risk`
- `evidence`
- `status`
- `reviewed_ref`
- `scope`