Team Debug — Competing Hypothesis Investigation

Spawn an agent team where each investigator pursues a different hypothesis about a bug, then they debate and converge on the root cause.

Key insight: Sequential debugging anchors on the first plausible explanation. Parallel investigation with adversarial debate produces more reliable root cause analysis.

Usage

/team-debug [description of the bug or symptom]

How to Execute

Step 1: Gather Bug Context

• Ask the user for symptoms if not provided via $ARGUMENTS
• Check recent git history, error logs, or failing tests
• Identify the affected area of the codebase
• Collect any reproduction steps

Step 2: Generate Hypotheses

Before spawning, brainstorm 3-5 plausible hypotheses based on the symptoms. Examples:

1. Race condition in concurrent code
2. Off-by-one error in boundary handling
3. Stale cache or state management bug
4. External dependency behavior change
5. Configuration drift or environment mismatch

Step 3: Spawn Investigation Team

Create a team with 3-5 investigators, one per hypothesis:

Template for each investigator:

You are investigator [N]. Your hypothesis is: "[hypothesis]".

Your job:
1. Gather evidence FOR your hypothesis (find code paths, logs, test failures that support it)
2. Gather evidence AGAINST your hypothesis (find code that should prevent this)
3. Try to DISPROVE the other investigators' hypotheses
4. Report your confidence level (0-100%) and evidence to the team

The bug symptoms are: [symptoms]
Affected area: [files/modules]
Reproduction steps: [if available]

When you have findings, message the other investigators to challenge their theories.
This is a scientific debate — the strongest surviving theory wins.

Step 4: Facilitate Debate

The lead should:

1. Let investigators work independently for the first pass (~5 min each)
2. After initial findings, have them challenge each other via messages
3. Track which hypotheses gain/lose evidence
4. Ask investigators to update their confidence levels
5. Converge on the most supported theory (highest confidence + most evidence)
6. Have the winning investigator propose a fix

Step 5: Verify & Fix

Once the team converges:

1. Present the root cause with supporting evidence
2. Propose a fix with a test that would have caught the bug (per project rules)
3. Ask the user to confirm before implementing
4. Clean up the team

Model Recommendations

• Lead: Opus (facilitates debate, synthesizes evidence, makes judgment calls)
• Investigators: Opus for complex/subtle bugs, Sonnet for straightforward ones

Example Invocations

/team-debug users report the app exits after one message instead of staying connected
/team-debug tilemap rendering has artifacts at chunk boundaries
/team-debug test_physics_step is flaky — passes 90% of the time
/team-debug resource loader returns None for valid UIDs intermittently
/team-debug signal dispatch ordering changed after the lifecycle refactor