/doc-review

name: doc-review
description: "Document review via Codex exec. Use when: reviewing .md docs, tech spec audit, document quality check. Not for: code review (use codex-code-review), test review (use test-review). Output: 5-dimension rating table + gate."
allowed-tools: Bash(git:*), Bash(node:*), Read, Grep, Glob, Task, Write
context: fork
agent: Explore

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

| Command | Description | Use Case | | ------------------- | ---------------------- | ----------------- | | `/codex-review-doc` | Codex reviews .md docs | Document changes | | `/review-spec` | Review tech spec | Spec confirmation | | `/doc-refactor` | Streamline documents | Doc too long | | `/update-docs` | Research & update docs | After code change |

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

| Condition | Action | |-----------|--------| | Paths specified | Use them — all of them, as one plan | | No path | `git diff --name-only HEAD` and untracked, filtered to `.md` | | Nothing changed | Report it and stop; there is no document to review |

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 `refer