doc-review

Files (4)

• SKILL.md
• codex-prompt-doc.md · references/
• documentation-contract.md · references/
• review-loop-doc.md · references/

SKILL.md (first lines)

# 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

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

```bash
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:

```json
{ "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

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness