review-plan

Run a fresh reviewer round against the current task plan, revise the <plan> section after every in-scope VERDICT: REVISE, and repeat until the plan reaches VERDICT: APPROVED, the loop hits 5 rounds, or the task must return to /apex:research or /apex:plan because the inputs are too weak for safe review.

Target: 2-3 rounds. Hard max: 5 rounds.

You can find tasks in ./apex/tasks/ or run with: /apex:review-plan [identifier] Load task file, extract the current plan, and start round 1.

1. Create a compact round summary for the reviewer:
   • Current plan snapshot
   • Contract and research constraints
   • Prior round findings and what changed since then
2. Spawn exactly one fresh subagent for the round
3. Instruct the subagent:
   • This is a read-only review round
   • Do not edit files
   • Review the plan as an adversary, not a collaborator
   • Inspect repo files if needed to verify feasibility
   • Focus on:
     • mandatory artifact completeness
     • architecture soundness
     • contract coverage
     • contract version / amendment acknowledgement
     • security concerns
     • edge cases and failure modes
     • concurrency, state, ordering, and race risks
     • pattern provenance and trust alignment
     • documentation drift
     • non-functional requirement coverage
     • validation quality and realism
     • implementation sequencing and dependency order
     • research-to-plan mismatches
4. Require the subagent to return this structure:

ROUND: [N]
VERDICT: [REVISE|APPROVED]
NEXT ACTION: [CONTINUE|RETURN_TO_RESEARCH|RETURN_TO_PLAN|IMPLEMENT]

MUST FIX
- ...

NON-BLOCKING
- ...

SUGGESTED PLAN EDITS
- ...

APPROVAL SUMMARY
- ...

Rules for the verdict:

• APPROVED only when there are no blocking issues left
• REVISE when any blocking issue remains
• Reviewer must not use softer top-line verdicts like PROCEED or RETHINK

Rules for NEXT ACTION:

• CONTINUE means the plan is reviewable and can be revised in place
• RETURN_TO_RESEARCH means the evidence base is too weak for safe review
• RETURN_TO_PLAN means the plan is below threshold or requires scope / contract rework
• IMPLEMENT is only valid with VERDICT: APPROVED

1. Extract the blocking findings
2. If NEXT ACTION is RETURN_TO_RESEARCH:
   • stop the loop
   • do not edit <plan>
   • instruct the user to run /apex:research [identifier]
3. If NEXT ACTION is RETURN_TO_PLAN:
   • stop the loop
   • do not edit <plan>
   • instruct the user to run /apex:plan [identifier]
4. Otherwise continue with in-scope plan fixes
5. Update the task's <plan> section directly to resolve them
6. Keep edits scoped to the plan:
   • preserve all 5 mandatory artifacts
   • preserve architecture decision, builder handoff, and contract validation
   • acknowledge contract version and any amendments
   • preserve or restore docs drift, pattern provenance, and NFR coverage checks
   • refine architecture choice
   • add missing mitigations
   • cover uncovered acceptance criteria
   • tighten sequencing
   • replace vague validation with concrete commands
   • clarify ownership of edge cases or concurrency handling
7. Do not edit <task-contract> or <research>
8. If a blocking issue cannot be fixed without changing contract scope, assumptions, or acceptance criteria:
   • stop the loop
   • report VERDICT: REVISE
   • set next action to RETURN_TO_PLAN
   • instruct the user to return to /apex:plan [identifier]
9. After editing the plan, validate the mutation before the next round:
   • reread the task file
   • confirm the <plan> block still parses and is isolated from surrounding sections
   • confirm the edit stayed scoped to <plan>
   • confirm required plan artifacts were not accidentally removed
   • if the task file is malformed, repair it before continuing; if that is not possible, stop and return to /apex:plan [identifier]
10. After each revision, summarize in chat:

• what the reviewer flagged
• what changed in the plan
• what remains to validate next round

11. Start the next round with a fresh reviewer subagent

If round 5 ends with VERDICT: REVISE:

• Stop the loop
• Set next action to RETURN_TO_PLAN
• Do not continue beyond 5 rounds
• Present the unresolved blockers
• Recommend returning to /apex:plan [identifier] for a larger rework

Round Status

• Round [N]: [REVISE|APPROVED]
• Repeat for each executed round, up to 5

Final Verdict

VERDICT: [REVISE|APPROVED]

Next Action

[RETURN_TO_RESEARCH|RETURN_TO_PLAN|IMPLEMENT]

Blocking Findings

• [Finding + exact fix, if any remain]

Plan Changes Made

• [High-signal summary of plan revisions applied during the loop]

Final Notes

• [If IMPLEMENT]: Ready for /apex:implement [identifier]
• [If RETURN_TO_RESEARCH]: Return to /apex:research [identifier]
• [If RETURN_TO_PLAN]: Return to /apex:plan [identifier]

• Missing mandatory plan artifacts or thin placeholder artifacts
• Missing or contradictory contract coverage
• Missing contract version / amendment acknowledgement
• Architecture that does not match research evidence
• Security-sensitive gaps with no mitigation or explicit exclusion
• Concurrency/state/order-of-operations risks left implicit
• Edge cases handled with wishful thinking
• Pattern claims that do not trace back to research or codebase evidence
• Documentation drift identified in research but absent from the plan
• Non-functional requirements without validation coverage
• Validation gates that are vague, manual-only, or not runnable
• File or dependency assumptions that do not match the repo