Iterative worker-reviewer cycle within a single session. You do the work, spawn a reviewer subagent to critique it, revise based on feedback, repeat until quality gate is met.
Core principle: First drafts are never final. Iterative critique produces better output than a single pass.
Platform note: This skill works best with agents that support subagent spawning. On platforms without that capability, simulate the reviewer step by opening a fresh chat context, pasting only the work product (no prior reasoning), and asking it to score 1-10 with specific feedback.
"implement X, use review-loop" or "run review-loop on the file I just wrote"| Setting | Default |
|---|---|
| Min loops | 2 |
| Max loops | 4 |
| Quality gate | 8/10 |
| Worker model | (your current model) |
| Reviewer model | (your current model or fast/balanced alternative) |
The reviewer task evaluates logic and constraints. The worker task writes and modifies code. Pick subagent capabilities accordingly.
CRITICAL RULE: The Reviewer must always be EQUAL TO or MORE POWERFUL than the Worker. If the reviewer is weaker than the worker, it cannot properly critique complex logic or catch subtle regressions.
| Task Complexity | Worker Capability | Reviewer Capability | Rationale |
|---|---|---|---|
| Simple/mechanical (CRUD, formatting, boilerplate) | Fast / Lightweight | Balanced | Lightweight worker is fast, balanced reviewer easily catches issues |
| Standard (features, refactors, docs) | Balanced | Balanced | Good mix of cost, speed, and quality |
| Complex (multi-file, integration, design) | Balanced | Advanced / Reasoning | Advanced reviewer catches subtle architecture issues, balanced worker can implement them |
| Very complex (security, quant, distributed systems) | Advanced / Reasoning | Advanced / Reasoning | Both need full context and reasoning power. Reviewer MUST match worker power. |
The golden rule: The worker must be smart enough to ACT on the reviewer's feedback. If the reviewer says "fix the race condition with a channel-based semaphore" and the worker can't reason about concurrency, the loop won't converge.
Escalation signal: If score doesn't improve after 2 consecutive loops with the same feedback, the worker model is too weak. Escalate:
Default behavior: Since you (the main agent) ARE the worker, spawn a reviewer subagent that matches or exceeds your current capability based on the task:
Users can override any default inline with their request. Parse these naturally:
"implement X with review-loop, quality gate 9, use advanced model for review, max 5 loops"
"polish this, 2 loops minimum, gate at 8"
"run review-loop with fast reviewer, max 2 loops"
"use review-loop, reasoning reviewer, quality gate 9, min 3 max 6"
Parsing rules:
flowchart TD
A[Do the work] --> B[Spawn reviewer subagent]
B --> C{Min loops met?}
C -- no, always continue --> E[Revise based on feedback]
C -- yes --> D{Score >= quality gate?}
D -- yes --> F[Final polish pass]
D -- no --> G{Max loops reached?}
G -- yes, stop anyway --> F
G -- no --> E
E --> B
F --> H([Done])
Complete the task as you normally would. Write the code, create the spec, implement the feature. Don't hold back — produce your best first attempt.
Use the Agent tool to dispatch a reviewer. The reviewer must:
Reviewer prompt template:
You are a critical reviewer. Score the following work 1-10 and provide specific, actionable feedback.
## What was done
{brief description of the task}
## Review criteria
{task-specific criteria — what matters for THIS task}
Examples of well-written criteria:
For a REST API endpoint:
- Correct HTTP status codes used
- Input validation present on all parameters
- Auth enforced; no unauthenticated access
- No N+1 query patterns
For a design doc:
- Problem statement is unambiguous
- Alternatives considered with trade-offs
- No hand-waving on implementation complexity
- Success metrics are measurable
For a data pipeline:
- Idempotent — safe to re-run
- Schema changes handled gracefully
- Failure modes documented
- PII handling addressed
## Instructions
1. Read the work carefully
2. Score 1-10 where:
- 1-3: Fundamentally broken or missing major requirements
- 4-6: Works but has significant issues
- 7-8: Good, minor issues only
- 9-10: Excellent, ready to ship
3. List specific issues with file:line references where applicable
4. For each issue, explain WHY it matters and WHAT to fix
5. Do NOT be polite — be honest and direct
6. State your score clearly as "Score: N/10"
## Files to review
{paste file contents or list file paths with relevant excerpts}
From the reviewer response, extract:
Report to the user:
Loop {N}/{max}: Score {X}/10
- {summary of key feedback points}
In this order:
Address the reviewer's feedback. Fix Critical and Important issues. Minor issues are optional. Then go back to Step 2.
Important: Each revision should be targeted. Don't rewrite everything — fix what the reviewer flagged. Maintain a mental list of ALL prior feedback to avoid regressions.
Once the loop exits (quality gate met or max loops hit):
| Task Type | Reviewer Should Focus On |
|---|---|
| Code | Correctness, edge cases, error handling, readability, no security issues |
| Spec/Design | Completeness, feasibility, no hand-waving, implementability |
| Refactor | No behavior changes, no regressions, cleaner than before |
| Writing | Clarity, structure, audience-appropriate, no fluff |
| Bug fix | Root cause addressed, regression test exists, no side effects |
| Infrastructure / IaC | Idempotency, least privilege, no hardcoded secrets, destroy safety |
| Database migration | Reversibility, index strategy, data loss risk, performance at scale |
| API design | Backward compatibility, auth, versioning, error contract |
| Test suite | Edge case coverage, no test interdependency, meaningful assertions |
User gives a task + says to use review-loop. You do the work AND run the review loop.
User: "Implement the caching layer. Use review-loop, quality gate 8."
You:
1. Implement caching layer
2. Spawn reviewer → Score 6, feedback: missing eviction, no TTL
3. Revise: add eviction + TTL
4. Spawn reviewer → Score 8, feedback: minor naming nit
5. Final polish, done
User already did work or you already did work. Just run the review loop on what exists.
User: "Run review-loop on the auth module I just wrote"
You:
1. Read the auth module
2. Spawn reviewer → Score 5, feedback: SQL injection, no rate limiting
3. Fix: parameterize queries, add rate limiter
4. Spawn reviewer → Score 8, approved
5. Done
Never:
If reviewer is wrong:
--- Review Loop: {task name} ---
Loop 1/4: Score 6/10
Reviewer: Missing input validation, no error handling for network timeout,
function too long (80 lines).
Action: Fixing all three issues.
Loop 2/4: Score 8/10
Reviewer: Clean. Minor: variable name `d` could be more descriptive.
Action: Quality gate met (8 >= 8). Final polish.
Result: 8/10 in 2 loops. Done.
MIT — free to use, adapt, and redistribute with any AI tool or platform. Attribution appreciated. Contributions welcome.