| name | plan-review |
| description | Use before presenting an implementation plan or design document to the user, before calling ExitPlanMode, or whenever you want a quality check on a plan/design ('check this plan', 'review my design before I share it', 'validate plan completeness'). Dispatches a sub-agent that scores the plan/design across four dimensions — feasibility, completeness, YAGNI, codebase alignment — and either passes it through or revises critical/major findings before user presentation. Orchestrator-level only; refuses sub-agent invocation. Trigger phrases include 'review this plan', 'check the design', 'validate the plan', 'before showing the user', 'pre-approval review', 'plan quality check'. |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
Requires Agent tool. If running as a sub-agent (Agent tool unavailable), STOP and return: "ERROR: /dso:plan-review requires Agent tool; invoke from orchestrator."
Plan Review
Orchestrator-level skill that dispatches a dso:plan-review sub-agent to review plans and designs before the user sees them. This skill runs at the orchestrator level — it is NOT itself dispatched as a sub-agent (the SUB-AGENT-GUARD above enforces this).
When to Invoke
MANDATORY before any of these:
- Presenting a design doc to the user for approval (brainstorming skill)
- Presenting an implementation plan to the user (writing-plans skill)
- Calling
ExitPlanMode (plan mode)
The hook on ExitPlanMode enforces this mechanically. For brainstorming and writing-plans, this is skill-enforced.
Parameters
| Parameter | Required | Default | Description |
|---|
artifact_type | Yes | — | "design" or "implementation_plan" |
artifact_path | Yes | — | Path to the plan/design file, or inline content |
Process
Step 1: Dispatch Review Sub-Agent
Launch a single sub-agent with the plan content and review rubric.
Model selection:
artifact_type: "design" → opus (architectural reasoning)artifact_type: "implementation_plan" → sonnet (structural analysis)
Sub-agent prompt: Read and fill placeholders in ${CLAUDE_PLUGIN_ROOT}/docs/workflows/prompts/plan-review-dispatch.md. Replace {artifact_type} and {artifact content} with actual values.
Inline dispatch is required — dso:plan-review is an agent file identifier, NOT a valid subagent_type value. The Agent tool only accepts built-in types (general-purpose, Explore, Plan, etc.). Read agents/plan-review.md inline and dispatch as subagent_type: "general-purpose" with the model below.
Launch with:
Agent tool:
subagent_type: "general-purpose"
model: opus (design) or sonnet (implementation_plan)
# Model rationale: design needs trade-off reasoning across architectural
# coherence (opus); implementation_plan needs structured analysis of task
# atomicity / dependency graph / TDD discipline (sonnet — haiku misses
# implicit coupling).
Step 2: Process Results
First, validate the sub-agent's output schema (schema-hash: 9dba6875b85b7bc3):
REPO_ROOT=$(git rev-parse --show-toplevel)
source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/deps.sh"
PLAN_OUT="$(get_artifacts_dir)/plan-review-output.txt"
cat > "$PLAN_OUT" <<'EOF'
<sub-agent output>
EOF
".claude/scripts/dso validate-review-output.sh" plan-review "$PLAN_OUT"
If SCHEMA_VALID: no — send a correction prompt to the sub-agent requesting the exact format; do not proceed until validation passes.
Then parse the validated output:
-
If VERDICT is PASS (all scores >= 4):
- Write the marker file (see below)
- Proceed to present the plan to the user
- Include a brief note: "This plan was reviewed by a sub-agent. No issues found."
-
If VERDICT is REVISE (any score < 4):
- Address each finding by severity: critical first, then major, then minor
- For critical/major findings: revise the plan directly
- For minor findings: revise if quick, otherwise note them for the user
- Do NOT re-run the review — one pass is enough. Note what was changed.
- Write the marker file
- Present the revised plan to the user with a summary of what the review caught and what was changed
Step 3: Write Marker File
After the review completes (pass or revise-then-fix), write the marker:
REPO_ROOT=$(git rev-parse --show-toplevel)
source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/deps.sh"
ARTIFACTS_DIR=$(get_artifacts_dir)
mkdir -p "$ARTIFACTS_DIR"
cat > "$ARTIFACTS_DIR/plan-review-status" << EOF
passed
timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
artifact_type={design|implementation_plan}
verdict={PASS|REVISE}
scores=feasibility:{N},completeness:{N},yagni:{N},codebase_alignment:{N}
EOF
The ExitPlanMode hook checks for this file.
What This Skill Does NOT Do
- No multi-stage review protocol (single pass only)
- No JSON schema output (findings are for the agent, not persisted)
- No automated revision cycles (agent fixes once, done)
- No conflict detection between findings
Common Mistake: Do NOT Use Code Review for Plans
/dso:review reviews completed code (diffs, test coverage, bugs). It is wrong for plans. Use this skill (/dso:plan-review) for plans and designs. See CLAUDE.md always:correct-review-tool and the review routing table in "Always Do These".
