investigate
Multi-provider adversarial investigation. Claude (Opus) and Codex (GPT, model from ~/.codex/config.toml) debate through structured rounds. Use for ideation, architecture decisions, risk analysis, or a
SKILL.mdskills/investigate/SKILL.md
GitHubInvestigate: Adversarial Multi-Provider Debate
Structured debate between Claude (Opus) and Codex (GPT, model from ~/.codex/config.toml) where they challenge each other's ideas through multiple rounds. Runs in background — you can continue working while the debate happens.
/investigate runs in background — adversarial Claude + Codex debate, returns convergence report
User-input prompt presentation in this skill follows the banner
convention in docs/user-input-banner-convention.md. The async-result
follow-up fork in "When Results Arrive" carries the AWAITING YOUR INPUT
banner.
Caveman activation in this flow
Caveman compression is mandatory in this flow. The wire prefix [COMPRESSION:terse] MUST be prepended to every subagent Task description and to every Codex MCP developer-instructions: field within this flow. Machine-output payloads (haiku scorer JSON, render_findings / dedupe_findings IO, parser inputs) are exempt per skills/caveman/SKILL.md §7.
When to use
- Architecture decisions ("should we use X or Y?")
- Risk analysis before major changes
- Evaluating tradeoffs between approaches
- Stress-testing an idea before implementation
- Any decision that benefits from adversarial scrutiny
Argument Parsing
$ARGUMENTSis the topic or question to investigate- Optional flags:
--rounds N— number of debate rounds (default 3, max 5)--codebase— include repository context in the debate (auto-detected if topic references code)--focus <area>— narrow the debate to a specific aspect
Examples:
/investigate should we migrate from Axelar to Wormhole for the bridge?
/investigate --rounds 4 --codebase is our current fee calculation safe against precision loss?
/investigate --focus security what are the risks of adding flash loan support?
Execution: BACKGROUND
DO NOT block the main conversation. Dispatch to the investigator agent and return control immediately.
Step 1: Parse arguments
Extract:
- topic: the core question
- max_rounds: from
--roundsor default 3 - codebase_context: true if
--codebaseflag or topic references files/code - focus: from
--focusor null
Step 2: Launch investigator agent
Use the Agent tool to launch the investigator subagent with run_in_background: true:
Prompt template:
Investigate the following topic through adversarial debate.
topic: [parsed topic]
max_rounds: [N]
codebase_context: [true/false]
focus: [area or "general"]
working_directory: [cwd]
[If codebase_context: brief summary of relevant files/architecture]
Step 3: Inform the user
Immediately respond:
Investigation started in background: "[topic]" Claude (Opus) and Codex (GPT, model from ~/.codex/config.toml) will debate for up to [N] rounds. I'll present the convergence report when they finish. You can continue working.
Then return control. Do NOT wait.
When Results Arrive
When the investigator agent completes:
- Present the convergence report to the user
- Highlight:
- Key agreements (high confidence conclusions)
- Unresolved tensions (genuine tradeoffs to decide on)
- Recommended approach (synthesized from both perspectives)
- Ask the user to pick the next move via the banner below.
⏸ AWAITING YOUR INPUT
Investigation finished — pick the next move.
investigate-deeper— re-open the debate with a narrower angle (e.g. a specific tension, a new constraint, an alternative framing).accept-and-proceed— take the current recommendation as the decision and move on.pivot— abandon this line and start a new investigation on a different angle.
Which path?
How the Debate Works (for context)
The investigator agent runs structured rounds:
- Claude generates a thorough position with rationale, risks, and tradeoffs
- Codex critiques via MCP — finds flaws, challenges assumptions, proposes alternatives
- Synthesis — identifies agreements, disagreements, evolved positions
- Convergence check — stops early if no new critiques emerge
- Repeat until converged or max rounds
Each round builds on the previous. Codex maintains conversation context via codex-reply threadId. Both sides must acknowledge good arguments from the other (intellectual honesty).
Tips
- Frame as a question, not a statement — "should we use X?" triggers better debate than "we should use X"
- Add constraints — "given our 2-week timeline" or "with 3 validators" narrows the debate productively
- Use --codebase for technical decisions — agents will read actual code instead of speculating
- 3 rounds is usually enough — use more only for genuinely complex tradeoffs
- Act on the results — the report is designed to be actionable, not academic