doc-review git:20260726.96786d1A

Immutable. This exact content is served forever at /api/v1/blob/749b9a6e1760b5ff.

---
name: doc-review
description: "Document review via Codex MCP. 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: mcp__codex__codex, mcp__codex__codex-reply, Bash(git:*), Read, Grep, Glob
context: fork
agent: Explore
---

# Document Review Skill

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

```
Determine target → Read content → Codex review (5 dimensions) → Rating table + Gate → Loop if Needs revision
```

### Step 1: Determine Target File

| Condition | Action |
|-----------|--------|
| Path specified | Use that path directly |
| No path | Auto-detect: git modified `.md` → staged `.md` → new `.md` |
| Multiple files | List and ask user which to review |

### Step 2: Read File Content

Read target file, save as `FILE_CONTENT`.

### Step 3: Codex Review

**First review**: `mcp__codex__codex` with doc review prompt. See `references/codex-prompt-doc.md`.

Config: `sandbox: 'read-only'`, `approval-policy: 'never'`

**Save the returned `threadId`.**

**Loop review**: `mcp__codex__codex-reply` with re-review template. See `references/review-loop-doc.md`.

### Step 4: Consolidate Output

Organize results into rating table + severity-grouped findings + gate.

## Review Dimensions

| Dimension           | Checks |
| ------------------- | ------ |
| Architecture Design | System boundaries, responsibilities, dependencies, extensibility |
| Performance         | Bottlenecks, concurrency, caching, resource usage |
| Security            | Data leakage, access control, input validation, error handling |
| Documentation Quality | Structure, completeness, accuracy, examples, docs-writing standards |
| Code Consistency    | Pseudocode matches codebase, referenced files exist, technical accuracy |

## Review Loop

**⚠️ @CLAUDE.md auto-loop: fix → re-review → ... → ✅ PASS ⚠️**

⛔ Needs revision → fix 🔴 items → `/codex-review-doc --continue <threadId>` → repeat until ✅ Mergeable.

Max 3 rounds (`fast` tier — docs are the tier's primary case). Still failing → report blocker.

**🔴 only.** 🟡 and ⚪ are non-blocking: log them and proceed.

```
[NIT_DEFERRED] file:line | issue | reason: sub-threshold-doc | <ISO8601>
```

That tag and field order are **hook-parsed** — `post-tool-review-state.sh` matches `[NIT_DEFERRED]` at column 0 and writes the entry to `.claude_nit_history.json` with a TTL, so the same 🟡 is not re-raised next session. `/codex-review-doc` is an eligible producer (the routing matches `codex-review`). Any other tag is behavior-layer prose that no hook reads.

The parse runs on the **reviewer's output**, which is why `references/codex-prompt-doc.md` asks Codex for a `### Deferred Findings` section. The same line typed into your own reply is readable but persists nothing.

Do not batch-fix 🟡/⚪ and re-review to confirm — that spends a round on findings the gate already declared non-blocking. The two exceptions are the same as for code (`@rules/auto-loop.md` § Sub-Threshold Findings): a one-line fix in a file already open, and a mis-marked security / data-integrity issue that should have been 🔴.

What counts as 🔴 is pinned in `references/codex-prompt-doc.md § Severity Calibration` — it is the reviewer prompt, not this file, that keeps the loop short.

## Verification

- [ ] Each issue tagged with severity (🔴/🟡/⚪)
- [ ] Gate is clear (✅ Mergeable / ⛔ Needs revision)
- [ ] Codex verified code-documentation consistency independently

## Required Actions

| Change Type | Must Execute                          |
| ----------- | ------------------------------------- |
| `.md` docs  | `/codex-review-doc` or `/review-spec` |
| Tech spec   | `/review-spec`                        |
| README      | `/codex-review-doc`                   |

## References

- Doc review prompt: `references/codex-prompt-doc.md`
- Review loop: `references/review-loop-doc.md`
- Standards: @rules/docs-writing.md

## Examples

```
Input: /codex-review-doc docs/features/xxx/tech-spec.md
Action: Read file → Codex doc prompt → Rating table + Findings + Gate

Input: /codex-review-doc
Action: Auto-detect changed .md → Codex doc prompt → Rating table + Gate

Input: Review this tech spec for me
Action: /review-spec → Check completeness/feasibility/risks → Output Gate

Input: This document is too long, streamline it
Action: /doc-refactor → Tabularize + Mermaid → Output comparison
```