Review (specs and plans)
Harness note. Skill names are written /name (Claude Code slash form); in Codex invoke the same skill as $name. Sub-agent dispatch is shown as Claude Code's Agent({ subagent_type: "general-purpose", … }) — in Codex spawn a sub-agent with the same prompt, or apply the contracts inline, in sequence, when sub-agents are unavailable.
This skill reviews artifacts you are about to build from — a spec or a plan.
It does not review the project. Code, UX, runtime, tests, security, dependencies and docs drift are covered by the review framework commands:
| Command |
Reviews |
/review-change |
correctness, tests, security of a change |
/review-experience |
real user flow in a browser |
/review-health |
architecture, dependencies, docs/contracts |
/review-release |
synthesis of the above into a ship decision |
Dispatch, don't self-review
Send the artifact to a subagent so the review is not anchored by whoever wrote it.
Agent tool:
subagent_type: "general-purpose"
name: "review-<spec|plan>"
prompt: |
OBJECTIVE: {what this spec/plan is for, 1-2 sentences}
UPSTREAM CONTEXT: {approved spec, or "no spec attached — skip scope check"}
ITERATION: {X}/3
{if iteration > 1: PREVIOUS FINDINGS: {fixed / outstanding}}
ARTIFACT:
{full text}
Review criteria: {inline the contents of rules/review-criteria.md}
The artifact lives in the Linear issue (D0/D4): get_issue <id> and paste the description's spec, or its ## Plan section, as {full text}; a plan split into sub-issues → paste each sub-issue's description in order. Without the Linear MCP, ask the user to paste it. Never go looking for a spec or plan file in the repo.
Do NOT paste codebase contents — the subagent can read and search the codebase and should look for itself.
Lens
- spec — completeness, ambiguity, feasibility, edge cases, success criteria
- plan — ordering, executable steps, verification path, missing files or dependencies, whether each phase ends in something runnable
Verdict handling
- EXECUTABLE: Yes → present the report. Done.
- EXECUTABLE: Partial → present the report. The user decides whether to proceed.
- EXECUTABLE: No → fix HIGH/CRITICAL in the artifact (
save_issue { id, patch } on the issue, after showing the change — D14), re-dispatch. Max 3 iterations.
- 3 iterations exhausted → stop and escalate to the user.
Rules
- Report findings before proposing fixes; order by severity; include file references.
- No findings → say so explicitly and name the residual risk.
- Do not self-congratulate or bury findings under a summary.
- Do not fix while in review mode unless asked.
Criteria detail: rules/review-criteria.md
1---2name: review3description: Review a spec or a plan before implementation starts — completeness, ambiguity, feasibility, executable steps, missing dependencies. For reviewing the project itself (code, UX, architecture, deps, docs) use the /review-change, /review-experience, /review-health and /review-release commands instead.4---56# Review (specs and plans)78> **Harness note.** Skill names are written `/name` (Claude Code slash form); in Codex invoke the same skill as `$name`. Sub-agent dispatch is shown as Claude Code's `Agent({ subagent_type: "general-purpose", … })` — in Codex spawn a sub-agent with the same prompt, or apply the contracts inline, in sequence, when sub-agents are unavailable.910This skill reviews **artifacts you are about to build from** — a spec or a plan.1112**It does not review the project.** Code, UX, runtime, tests, security, dependencies and docs drift are covered by the review framework commands:1314| Command | Reviews |15| --- | --- |16| `/review-change` | correctness, tests, security of a change |17| `/review-experience` | real user flow in a browser |18| `/review-health` | architecture, dependencies, docs/contracts |19| `/review-release` | synthesis of the above into a ship decision |2021## Dispatch, don't self-review2223Send the artifact to a subagent so the review is not anchored by whoever wrote it.2425```26Agent tool:27 subagent_type: "general-purpose"28 name: "review-<spec|plan>"29 prompt: |30 OBJECTIVE: {what this spec/plan is for, 1-2 sentences}31 UPSTREAM CONTEXT: {approved spec, or "no spec attached — skip scope check"}32 ITERATION: {X}/333 {if iteration > 1: PREVIOUS FINDINGS: {fixed / outstanding}}3435 ARTIFACT:36 {full text}3738 Review criteria: {inline the contents of rules/review-criteria.md}39```4041The artifact lives in the Linear issue (D0/D4): `get_issue <id>` and paste the description's spec, or its `## Plan` section, as `{full text}`; a plan split into sub-issues → paste each sub-issue's description in order. Without the Linear MCP, ask the user to paste it. Never go looking for a spec or plan file in the repo.4243Do NOT paste codebase contents — the subagent can read and search the codebase and should look for itself.4445## Lens4647- **spec** — completeness, ambiguity, feasibility, edge cases, success criteria48- **plan** — ordering, executable steps, verification path, missing files or dependencies, whether each phase ends in something runnable4950## Verdict handling5152- **EXECUTABLE: Yes** → present the report. Done.53- **EXECUTABLE: Partial** → present the report. The user decides whether to proceed.54- **EXECUTABLE: No** → fix HIGH/CRITICAL in the artifact (`save_issue { id, patch }` on the issue, after showing the change — D14), re-dispatch. Max 3 iterations.55- **3 iterations exhausted** → stop and escalate to the user.5657## Rules5859- Report findings before proposing fixes; order by severity; include file references.60- No findings → say so explicitly and name the residual risk.61- Do not self-congratulate or bury findings under a summary.62- Do not fix while in review mode unless asked.6364Criteria detail: [rules/review-criteria.md](rules/review-criteria.md)
mxrsv