Doc Review

Document Review Skill

Read first: references/documentation-contract.md — the split procedure, the functional-document exemption and the comment-block exemption list that a review of a feature document or a comment migration judges against (rules/docs-numbering.md and rules/docs-writing.md are its resident cores). If that Read fails, stop and report it; do not review from memory.

Trigger

• Keywords: review doc, document review, tech spec review, review-spec, doc-refactor, streamline doc

When NOT to Use

• Code review (use codex-code-review)
• Test coverage review (use test-review)
• Just want to read a document (use Read directly)

Commands

Workflow: /codex-review-doc

Target set → Deterministic checks → Resolve profiles + batches → Codex review per batch → Rating table + Gate → Loop

All changed .md in one change are one review plan. The plan is the unit; it holds one or more physical batches, and within the budget it is exactly one batch and therefore one dispatch. Reviewing file-by-file is what this workflow replaced — it multiplied a three-file change into three whole- document reviews.

Step 1: Determine the Target Set

Never narrow a multi-file change to one file, and never ask the user to pick one. A file the plan drops is a file nothing reviewed.

Step 2: Deterministic Checks First

node scripts/check-doc-links.js --root "$(git rev-parse --show-toplevel)" <changed .md paths>

Resolves the repo-local file links it can classify, prints the ones that do not resolve, and prints unresolved — how many link shapes it declined to classify. Heading fragments are out of scope: [x](#frag) is dropped uncounted the way an external URL is, and [x](./a.md#frag) is checked as a link to a.md alone. A dead #fragment is therefore not a finding this step establishes, and the reviewer is free to raise one.

Scan only the paths that exist in the working tree. A deleted .md (the resolver reports it deleted: true) is omitted from this scan — passing it produces an unreadable failure that hands the reviewer a defect when the deletion is the change. Its review copy is git show HEAD:<path>, and the prompt says so per file.

Bash(node:*) and Task are in allowed-tools since review-loop-resilience (2026-08-23): the fallback dispatch below names scripts/lib/review-dispatch.js and scripts/validate-family-sentinel.js as steps of this workflow, and a named step should not stall on a permission prompt mid-review. The earlier deliberate omission protected against unnamed node invocations riding a review's grant; the boundary is now behavioural — this workflow invokes node only for the scripts its steps name (the link check, the profile resolver, the dispatch decision, the sentinel validator, the state note). Advisory input, not a gate: it always exits 0, and its output is fed to the reviewer as findings already established so the LLM does not spend a pass rediscovering them. markdownlint does not resolve links, so nothing else answers this.

Pass both fields to the prompt, and never failures alone. It is a scanner, not a CommonMark parser — this repository ships zero dependencies — so failures: [] settles the link question only alongside unresolved: 0. With unresolved > 0 that many link shapes went unchecked, and saying "already settled" over them is the one way this advisory input can cost a review rather than save one.

Step 3: Resolve Profiles and Batches

node scripts/resolve-review-profile.js --tier <effective tier> --files <a.md,b.md> --root "$(git rev-parse --show-toplevel)"

Emits a per-file profile with the reasons it is not shallower, plus the batch plan. Richer inputs — the ## sections a shallow profile is confined to, and whether code landed with the change — go in via --plan <file|->, a JSON document of the same shape the resolver prints:

{ "tier": "standard", "code_changed": false,
  "files": [ { "path": "docs/features/x/2-tech-spec.md",
               "profile": "living-sync", "sections": ["3. Design"] } ] }

Three things this step decides, and none of them is negotiable afterwards:

• The profile is resolved before the prompt is built. A shallow prompt for a change that did not earn one is never assembled, so there is no mismatch to detect afterwards and nothing to poison.
• Escalation is one-way and per file. One file escalating raises that file's questions and the batch's shared dimensions; it never withdraws another file's record-diff exemption.
• An over-budget plan splits loudly. Say which batches were produced and why, then dispatch each. Never claim one dispatch you did not make, and never drop a file to fit.

Step 4: Codex Review, One Dispatch Per Batch

First review: dispatch per @skills/codex-code-review/references/codex-transport.md § Start with the doc review prompt. See references/codex-prompt-doc.md.

Save the returned threadId — one per batch.

Loop review: dispatch per § Resume with the re-review template. See references/review-loop-doc.md — its Loop Rules carry the thread-rotation clause (central contract).

codex_fail → fallback carries the gate (adapter exit 1 only — @skills/codex-code-review/references/codex-transport.md § Completion state machine: a pending or unknown completion keeps the gate open with no fallback, exit 2 is a configuration error, and an alloc/cleanup failure is a lifecycle error) (@rules/auto-loop.md § Review Dispatch): decide via scripts/lib/review-dispatch.js (contract:'doc'), record [REVIEWER_FALLBACK] plane=doc_review from=codex to=contract-neutral-reviewer reason=<…> | <ISO8601> (sticky for this change), dispatch contract-neutral-reviewer via Task with references/codex-prompt-doc.md as the governing template — batch manifest, profiles and frozen file list included (P3 = one retry on a fresh instance) — and validate the raw report with node scripts/validate-family-sentinel.js doc before adopting the verdict (exactly one of ✅ Mergeable / ⛔ Needs revision, no foreign terminal). Fallback agents are stateless, so each loop round is a fresh dispatch. Carriers exhausted → no gate sentinel, behaviour-layer ⚠️ Need Human, nothing noted.

Stop cat-ing whole existing files into the prompt. Codex has sandbox access; the prompt carries the file list, each file's profile, and what that profile says to read.