| name | oracle-review |
| model | opus |
| description | Run iterative oracle + agent hardening loop on any artifact (designs, plans, beads, architecture) until findings converge to near-zero. Combines /swarm-oracle with /swarm-review in alternating rounds. Use for the full hardening cycle, not just a single oracle pass. For oracle-only, use /swarm-oracle. For bead-only hardening, use /swarm-beads-quality. |
| triggers | ["oracle review","hardening loop","iterate until converged","full review cycle"] |
| argument-hint | <target: design|plan|beads|architecture> [--rounds N] |
Oracle Review Skill
Oracle policy (2026-06): Fable (claude-fable-5) is the primary oracle. By
default the FOR/AGAINST sessions below run as two fresh Fable subagents (Agent
tool with model: "fable"; Fable is not reachable through PAL). The PAL 2x GPT-Pro
setup is the escalation tier — extremely important or complex validations only, and
always paired with a Fable consultation on the same prompt. See /consult-oracles
and the Oracle Consultation Policy in ~/CLAUDE.md.
Two-part process: (1) oracle consensus validation with FOR/AGAINST stances,
then (2) iterative hardening loop until findings converge to near-zero.
When to Use
- After design completion (validate UX + architecture)
- After implementation planning (validate feasibility + correctness)
- After bead creation (validate readiness + completeness)
- After architecture decisions (validate scope + approach)
- Any high-stakes decision needing external challenge
When NOT to Use
- Quick questions or second opinions (use
/swarm-oracle-standalone)
- Code review (use
/swarm-agents type=review)
- Simple validation that doesn't need adversarial challenge
Part 1: Oracle Consensus Validation
Setup
Run 2 concurrent oracle sessions:
- Default tier: two Fable subagents (
Agent, model: "fable"), one FOR stance, one AGAINST stance, spawned in a single message
- Escalation tier (extremely important/complex only): PAL MCP
consensus with 2x GPT-5.5-Pro (FOR + AGAINST), plus a parallel Fable consult on the same prompt
Oracle Prompt Template
Evaluate the following [ARTIFACT_TYPE] for [FEATURE]:
[ARTIFACT CONTENT or reference to document]
Score 1-10 on:
1. Correctness — Are the technical decisions sound?
2. Completeness — Are there gaps or missing considerations?
3. Consistency — Do parts contradict each other?
4. Feasibility — Can this be implemented as specified?
5. Quality — Does this meet production standards?
For each issue found, provide:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- Location: Which section/bead/decision
- Problem: What is wrong
- Recommendation: Specific fix
Do NOT say "looks good" without specific evidence.
Produce at least 3 actionable findings per category.
Interpreting Results
| Score | Meaning | Action |
|---|
| 9-10 | Excellent | Proceed, apply minor findings |
| 7-8 | Good with issues | Fix all CRITICAL/HIGH, proceed |
| 5-6 | Significant problems | Fix all issues, re-validate |
| <5 | Fundamental issues | Redesign, then re-validate |
Both oracles typically converge on similar scores. If they diverge by >2 points,
investigate the disagreement — it usually reveals a genuine ambiguity.
Apply Corrections
After each oracle round:
- Compile all findings from both stances
- Deduplicate (FOR and AGAINST often find same issues from different angles)
- Prioritize: CRITICAL first, then HIGH
- Apply fixes to the artifact
- Document what changed and why
Part 2: Iterative Hardening Loop
After oracle validation, run hardening rounds until convergence.
Round Structure
Each round has 3 steps:
Step A: Review (10 Opus agents via /swarm-agents type=review)
- Each agent reviews with a different lens
- Finds issues, inconsistencies, gaps
- Output: list of findings per agent
Step B: Fix
- Compile all findings
- Apply fixes (6-8 Opus agents for large artifacts)
- Each fix validated against the original plan/design
Step C: Validate Fixes
- Oracle round on the fixed artifact
- OR agent review of just the changes
- Confirm fixes don't introduce new issues
Convergence Signal
Track issues found per round:
| Round | Issues Found | Action |
|---|
| 1 | 15-20 | Expected — many first-pass issues |
| 2 | 8-12 | Good — deeper issues surfacing |
| 3 | 3-5 | Converging — mostly edge cases |
| 4 | 0-2 | Done — ready to ship |
Stop when a round finds <= 2 non-trivial issues. Typical: 3-4 rounds.
Hardening Agent Prompt Template
You are hardening [ARTIFACT] for [FEATURE].
Round {N} of iterative review.
Previous rounds found and fixed:
[SUMMARY OF PRIOR FINDINGS]
Your lens: [SPECIFIC_LENS]
Review the artifact and:
1. Check that prior fixes are correctly applied
2. Find NEW issues not caught in earlier rounds
3. Verify cross-cutting concerns are embedded (not just referenced)
4. Check acceptance criteria are Given/When/Then format
5. Verify file paths exist and are correct
6. Ensure no bead is >3 files (split if needed)
For beads specifically:
- Each bead must be self-contained (implementable without reading other beads)
- Dependencies must form a DAG (no cycles)
- Test beads must reference specific test methods/classes
- Acceptance criteria must be machine-verifiable
Target-Specific Guidance
Design Validation
Oracle focus: UX soundness, information architecture, interaction model consistency,
accessibility, progressive disclosure balance, terminology.
Plan Validation
Oracle focus: Feasibility, file-level correctness, dependency ordering, risk coverage,
test strategy completeness, migration safety.
Bead Validation
Oracle focus: Self-containment, AC specificity, dependency DAG, file path accuracy,
test coverage, priority ordering, cross-cutting embedding.
Architecture Validation
Oracle focus: Rewrite scope (not too much/little), backward compatibility, migration path,
performance impact, data integrity, rollback strategy.
Full Hardening Pipeline Example
Phase 1: Oracle (2x Fable FOR/AGAINST; escalate to 2x GPT-5.5-Pro + Fable if extremely important)
-> Fix CRITICAL/HIGH findings
Phase 2: Agent Review (10 Opus, multi-lens)
-> Fix all findings
Phase 3: Oracle (2x Fable FOR/AGAINST) on fixes
-> Verify fixes, find remaining issues
Phase 4: Agent Hardening (8 Opus, fresh eyes)
-> Embed cross-cutting, convert ACs, split oversized
Phase 5: Final Correctness (10 Opus)
-> Verify everything, fix last issues
-> If <= 2 issues: DONE
-> If > 2 issues: repeat from Phase 3
Key Rules
- Always run both FOR and AGAINST — single-stance misses adversarial findings
- Fix before re-validating — never run a new round on unfixed artifacts
- Track convergence — if issues aren't decreasing, the artifact needs redesign, not more rounds
- Validate fixes against plan — hardening must not drift from the original design intent
- Oracle before agents, agents before oracle — alternate perspectives for best coverage
- Verify PAL MCP is running before launching GPT/Gemini oracle sessions (agents silently fall back to self-analysis without it); Fable subagents need no PAL
