| name | quality-review |
| description | Structured 3-agent quality review using parallel simplifier, adversarial-reviewer, and chaos-engineer agents. Use when evaluating plans, designs, PRDs, architecture decisions, or any proposal before implementation. Three non-overlapping lenses — KISS/YAGNI, evidence/reasoning, robustness/edge cases. |
Quality Review
A structured interrogation methodology using three review agents in parallel to stress-test proposals before committing to them. Each agent attacks a different axis with no overlap.
The Three Lenses
| Agent | Model | Lens | Asks |
|---|
simplifier | Sonnet | KISS / YAGNI — complexity, abstractions, duplication | Is this the simplest way? |
adversarial-reviewer | Opus | Evidence, assumptions, logical gaps | Is this the right thing? |
chaos-engineer | Sonnet | Robustness, edge cases, failure modes | What breaks this? |
Why three: the simplifier prevents over-engineering, the adversarial reviewer prevents under-thinking, the chaos engineer prevents under-stress-testing. Together they catch design failures across complexity, correctness, and robustness.
Why Opus for adversarial: adversarial reasoning needs to find non-obvious logical gaps and challenge framing itself. The other two work in well-defined search spaces (complexity patterns, failure patterns) and run fine on Sonnet.
When to Use
- Before implementing a new phase, feature, or architecture change
- When making irreversible decisions (schema design, MCP server architecture, skill interfaces, API contracts)
- After a research team or planning agent produces recommendations — before accepting them
- When the user asks "is this right?" or "should I do this?"
- Before publishing public-facing copy or signing off on a deliverable
- Before merging a structural PR
When NOT to Use
- Trivial changes (single-file edits, config tweaks, typo fixes)
- Pure information requests (quality-review is for proposals, not questions)
- Code review of already-implemented code where the design is locked — use a code-review pass instead
The Pattern
Round 1 — Initial Review
Spawn all three agents in parallel against the proposal:
Agent(simplifier): "Review this proposal. Find over-engineering and simpler alternatives."
Agent(adversarial-reviewer): "Review this proposal. Challenge assumptions and find weaknesses."
Agent(chaos-engineer): "Review this proposal. Find edge cases, failure modes, and robustness gaps."
Feed each agent:
- The proposal / plan / PRD being reviewed (full text or file path)
- Relevant context (existing PRDs, CLAUDE.md, current project state)
- The specific decision being made, if there is one
Collect: numbered findings grouped by priority (Critical / High / Medium / Low) from each agent.
Round 2 — Synthesis
Synthesize all three agents' findings into a unified report:
- Where do they agree? (high-confidence findings — implement these)
- Where do they disagree? (needs human judgment — surface the tension, don't resolve it)
- What's the combined recommendation? (specific structural changes to PRD, design, or implementation plan)
Present to the user for decision.
Round 3 — Re-Review (if context changes)
When the user provides new context that changes the framing (e.g., "this is a template, not a one-off" or "this is throwaway code"), re-engage the relevant agents with the updated context:
Agent(<lens>): "You previously found X. The user clarifies Y. Re-evaluate."
This round often produces the strongest insights — agents refine their positions with better information. Don't run more than 2 re-review rounds unless genuinely new information arrives.
Round 4 — Convergence
Final synthesis. Typically you have:
- Findings all three agents agree on → implement
- Findings resolved by new context → document the resolution
- Remaining disagreements → user decides
- Specific structural recommendations → integrate into PRD / design doc / ROADMAP immediately, don't leave as floating review notes
Prompt Structure
When spawning each review agent, always provide:
- Role reminder — "You are the Simplifier / Adversarial Reviewer / Chaos Engineer."
- The artifact — full text of what's being reviewed, or a file path with explicit instruction to read it
- Context — existing PRD, project state, user constraints (≤200 words, only what's relevant)
- Specific question — what the user is actually deciding (not just "review this")
Keep the prompt under 300 words. Over-specified prompts constrain the agent's judgment and waste context.
Outputs
Quality review produces:
- Findings table — numbered, prioritized, with all three agents' positions
- Structural recommendations — specific changes to the PRD or design
- Decision items — things only the user can resolve
All accepted recommendations should be integrated into the source artifact (PRD, design doc, ROADMAP) immediately, not left as floating review notes.
Anti-Patterns
- Don't run quality-review on trivial changes
- Don't run more than 2 rounds without genuinely new context
- Don't treat agent findings as authoritative — they inform user judgment, they don't override it
- Don't let review become a substitute for building — the goal is better decisions, not more documents
- Don't skip the chaos-engineer when the proposal "feels safe." Safety bias is exactly when chaos catches the most.
Synthesis via knowledge-synthesizer
After Round 1 gathers findings from the three agents in parallel, invoke knowledge-synthesizer to combine the outputs rather than hand-rolling the merge. The synthesizer:
- Identifies findings 2+ agents independently surfaced (high confidence)
- Surfaces unique findings from a single agent (still data, not consensus)
- Preserves disagreements explicitly (does not force resolution)
- Flags coverage gaps
For Round 2 re-engagement after context shifts, run the affected agents in parallel via multi-agent-coordinator (so a failure in one does not stop the others), then re-synthesize via knowledge-synthesizer.
Parallel spawn discipline
The three review agents run truly in parallel — spawn them via multi-agent-coordinator, do not serialize. The coordinator tracks state, handles partial failures, and returns the combined results to the synthesizer.
