/review-spec

name: review-spec
description: "Review technical spec documents from completeness, feasibility, risk, and code consistency perspectives."
allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(node:*), Write

Review Spec

Trigger

• Keywords: review spec, spec review, tech spec review, review-spec

When NOT to Use

• Code review (use `/codex-review-fast`)
• General document review (use `/codex-review-doc`)
• Writing a new spec (use `/tech-spec`)

Relationship to `/codex-review-doc`

Both are **doc-plane producers of the same gate**, dispatched over the same Codex exec transport (`@skills/codex-code-review/references/codex-transport.md`) and emitting the same sentinel pair. They differ only in review depth and dimensions: `/review-spec` is the design-landing depth (completeness, feasibility, risk, code consistency, test strategy), `/codex-review-doc` is the general document depth. Loop mechanics, severity calibration and `[NIT_DEFERRED]` handling are shared — see `@skills/doc-review/SKILL.md`.

**Why not an Agent dispatch.** The gate verdict is behaviour-layer: it comes from the reviewer's report, and `review-state.js note` records it (`@rules/auto-loop.md` § Enforcement — nothing parses reviewer output; hooks are reminders). What makes a verdict *usable* is that a contract-aware reviewer produced it against this family's template and sentinels. A built-in agent dispatched ad hoc is not that reviewer and its output closes nothing. Dispatching Codex over the shared transport is what makes the verdict this skill's to note. See `@rules/auto-loop.md` § Review Dispatch.

Codex Dispatch

**Bind every placeholder before writing `prompt.md`.** The body below is body-only, so nothing evaluates an expression inside it: `${FILE_PATH}` and `${PROJECT_ROOT}` must carry real values by the time the file is written, or the `cat ${FILE_PATH}` instructions reach Codex as literal text and cannot be run.

You are a senior technical spec reviewer. Perform a **Document Review** of the technical specification below, at design-landing depth.

Document Info

• Path: ${FILE_PATH}
• Type: technical specification
• Project root: ${PROJECT_ROOT}

⚠️ Important: You must independently read and research the project ⚠️

Do NOT expect pre-provided file content. Read the spec and research the project yourself using your sandbox access. The spec makes concrete claims about this repository — verify them against the actual files rather than taking them on trust.

Document Reading (Priority)

1. Read the full document: `cat ${FILE_PATH}` 2. If long: `cat ${FILE_PATH} | head -300` then `cat ${FILE_PATH} | tail -200`

Code-Documentation Consistency Research

1. Project structure, discovered rather than assumed: `ls` at the repository root, then the directories it actually shows — do not assume a `src/` layout; many repositories, this one included, have none 2. Search for every file, function, flag and command the spec names: `grep -rn "keyword" . -l --include="*.ts" --include="*.js" --include="*.sh" | head -10` 3. Read related files: `cat <file-path> | head -100` 4. Verify: do referenced files exist? Are names correct? Do described behaviours match code?

Review Dimensions

| # | Dimension | Checks | |---|-----------|--------| | 1 | Completeness | Are requirements, scope, risks and work breakdown all present and specific | | 2 | Feasibility | Can this be built as described, with the dependencies it names | | 3 | Risk Assessment | Are the real failure modes identified, and does each have a bound | | 4 | Code Consistency | Do referenced files/functions exist and behave as described (**verify with grep/cat**) | | 5 | Test Strategy | Is every acceptance criterion mapped to evidence; are guards two-directional |

Severity Calibration ⚠️

A 🔴 blocks the document and costs a full review round. Reserve it for defects that would **mislead a reader into building the wrong thing**:

| Mark 🔴 | Do NOT mark 🔴 | |---------|----------------| | A described file, function, flag or command that does not exist | Wording that could be clearer | | A described behaviour that contradicts what the code actually does | A section you would have structured differently | | A security or data-handling design that is wrong or unsafe | A missing section that no rule requires | | An internal contradiction — two passages that cannot both be true | Prose where a table would be tidier | | A broken cross-reference, or a step whose stated dependency is not met by its own ordering | Hypothetical future concerns not present in the change |

Do not manufacture findings to fill a section. An empty 🔴 section is a normal outcome.

Output Format

Your report **must** begin with the literal line `## Document Review`. Nothing parses it — the verdict is behaviour-layer and `review-state.js` records only an explicit `note` (`@rules/auto-loop.md` § Enforcement). The header matters for the reader: it is what tells a document review apart from a code or security review in a transcript.

Document Review

Review Summary

| Dimension | Rating (1-5⭐) | Notes | |-----------|----------------|-------| | Completeness | ... | ... | | Feasibility | ... | ... | | Risk Assessment | ... | ... | | Code Consistency | ... | ... | | Test Strategy | ... | ... |

🔴 Must Fix (blocking — see Severity Calibration)

• [Section/Line] Issue description -> Fix recommendation

(Write `None` if there are none.)

🟡 Suggested Changes (non-blocking)

• [Section/Line] Issue description -> Fix recommendation

⚪ Optional Improvements

• Suggestion

Deferred Findings

For every 🟡 and ⚪ above, emit one line here, starting at column 0:

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

Do not reorder the fields and do not use a different tag. Omit this section entirely if there are no 🟡 or ⚪ items.

Gate

End the report with **exactly one** verdict terminal, alone at column 0 on the final line — t