model-research/review-prompts/ORCHESTRATION.md

Multi-Model Review Orchestration

When Rodin is asked to review a PR (e.g., "review PR 630", "look at PR #625"), use this orchestration pattern instead of a single-pass review.

Source of Truth

Specialized prompt files live at: ~/.openclaw/workspace/review-prompts/

• sonnet.md — structural/pattern review (Sonnet's mandate)
• gpt5.md — semantic/domain/concurrency review (GPT-5's mandate)
• opus.md — design coherence/contradiction review (Opus's mandate)

These same files are used by CI (review-bot via system-prompt-file). Update one place → both paths improve.

Decision: How Many Models?

PR touches...	Models to run
Tests only, config, deps	Sonnet only (structural)
Application code (non-core)	Sonnet + GPT-5
Core domain (order_management, ledger, risk, decision_engine)	Sonnet + GPT-5 + Opus
Architecture docs or design docs	GPT-5 + Opus (skip Sonnet)
Kill switch, reconciliation, or financial calculations	ALL THREE + narrow deep-pass

Orchestration Steps

1. Gather Context (do this yourself, don't delegate)

• Fetch PR metadata, diff, existing reviews (same as Phase 0-1 of pr-review skill)
• Identify what files are touched → determines which models to spawn
• Fetch linked issue/AC if present

2. Spawn Specialized Sub-Agents

Spawn sub-agents in parallel. Each gets:

• The full diff
• The relevant prompt file content (read from review-prompts/)
• Conventions file (CLAUDE.md)
• Patterns (from elixir-patterns/phoenix-conventions repos if applicable)
• Instruction: "Output structured findings as JSON. Do not post to Gitea."

sessions_spawn(model="sonnet", task="<sonnet prompt + diff + context>")
sessions_spawn(model="gpt5", task="<gpt5 prompt + diff + context>")
sessions_spawn(model="opus", task="<opus prompt + diff + context>")  # if design PR

3. Synthesize Results

After all sub-agents complete:

1. Deduplicate — if Sonnet and GPT-5 found the same issue, keep GPT-5's version (deeper explanation) and note "(also caught by Sonnet)"
2. Rank by severity — BLOCKER > MAJOR > MINOR > NIT
3. Group by category:
   • 🏗️ Structural (from Sonnet)
   • 🧠 Semantic/Domain (from GPT-5)
   • ⚖️ Design Coherence (from Opus)
4. Call out unique contributions — "Only GPT-5 caught: ..." / "Only Opus caught: ..."
5. Actionable fix list: Real bugs → must fix. Theoretical → discuss. Style → fix if cheap.

4. Present to Aaron

Format as a unified report with clear sections. Include:

• Overall verdict (APPROVE / REQUEST_CHANGES)
• Per-model findings (deduplicated, categorized)
• Recommended actions
• Any unresolved existing feedback from other reviewers

5. Post (if requested)

If Aaron says "post it" or "looks good, post":

• Use the pr-review skill's Phase 6 posting mechanics
• Post as a single unified review (not three separate ones)
• Use the rodin Gitea token for posting

Narrow Deep-Pass (for financial/safety PRs)

After the main review, if the PR touches financial logic:

1. Extract ONLY the changed financial logic (strip test code, config, docs)
2. Ask GPT-5 a single focused question:
   • "Can this code produce a silently incorrect financial calculation? Show the specific input that produces a wrong number."
3. If findings emerge, add them to the report under a "🎯 Deep Analysis" section

Timing Expectations

Configuration	Expected time
Sonnet only	~30s
Sonnet + GPT-5	~60s (parallel)
All three	~90s (parallel, Opus may be faster)
+ Deep pass	+45s (sequential after main review)

What This Replaces

This replaces the old single-pass pr-review for on-demand reviews. The pr-review skill is still used for its Phase 0 (PR identification), Phase 1 (context gathering), Phase 4 (existing feedback), Phase 6 (posting mechanics), and Phase 7 (walk-through). The REVIEW itself (Phase 3) is now multi-model.

The CI twins (review-bot) continue running independently — they're the automated safety net. On-demand reviews are the deep-dive when Aaron wants human-quality analysis.