| name | team-debug |
| description | Debugs issues using competing hypotheses in parallel via agent teams. Multiple teammates investigate different theories simultaneously and challenge each other's findings to converge on the root cause. Use when user says "team debug", "parallel debug", "investigate with team", "competing hypotheses", "debug in parallel", or when the root cause is unclear and multiple theories are plausible. Do NOT use for obvious bugs with clear stack traces — debug directly instead. Do NOT use when agent teams are not enabled.
|
| argument-hint | [bug description, error message, or issue number] |
| context | fork |
| metadata | {"author":"roberto-ramirez","version":"1.0.0","category":"agent-teams","tags":["debugging","agent-teams","parallel","investigation","hypotheses"]} |
/team-debug
You are orchestrating parallel debugging with competing hypotheses using agent teams. Multiple investigators test different theories simultaneously and debate to converge on the root cause.
Input
$ARGUMENTS
If $ARGUMENTS is empty, ask the user to describe the bug, symptoms, or error they're seeing.
Step 1 — Understand the symptoms
Before forming hypotheses, gather facts:
- Read the error message, stack trace, or bug report
- Identify the affected code paths
- Note when it started (recent changes? new deploy? environment change?)
- Check recent commits that might be related:
git log --oneline -20
Step 2 — Form competing hypotheses
Based on the symptoms, generate 3-5 distinct hypotheses about the root cause. Each hypothesis should be:
- Plausible given the symptoms
- Testable — there's a way to prove or disprove it
- Different from the others — don't create variations of the same theory
Present the hypotheses to the user:
Based on the symptoms, here are the competing hypotheses:
1. [Hypothesis A] — [why it's plausible]
2. [Hypothesis B] — [why it's plausible]
3. [Hypothesis C] — [why it's plausible]
Creating a debug team to investigate in parallel...
Step 3 — Create the debug team
Create an agent team to investigate a bug. Spawn one teammate per hypothesis.
Each investigator must:
1. Investigate their assigned hypothesis
2. Gather evidence for AND against their theory
3. Share findings with other teammates
4. Actively challenge other teammates' theories
5. Converge toward the most supported explanation
This is a scientific debate — the theory that survives scrutiny is the answer.
Spawn prompt for each investigator
Each teammate receives:
- The full bug description and symptoms
- Their assigned hypothesis
- Instruction to gather evidence both FOR and AGAINST their theory
- The files/areas most relevant to their hypothesis
- Instruction to message other teammates with findings that affect their theories
Encourage adversarial collaboration
Teammates should actively challenge each other's findings. When one investigator
finds evidence, others should try to find counter-evidence. The goal is the truth,
not winning — investigators should abandon their hypothesis if evidence disproves it.
Step 4 — Monitor the investigation
While teammates work:
- Watch for messages between teammates
- Note when hypotheses are eliminated
- If all teammates converge on the same root cause, that's a strong signal
- If teammates are going in circles, redirect with new evidence or constraints
Intervention triggers
- Teammate stuck in a loop: Provide new context or narrow their search
- Two teammates converging: Ask them to verify each other's evidence
- All hypotheses eliminated: Form new hypotheses based on what was ruled out
- One clear winner: Ask remaining teammates to try to disprove the leading theory
Step 5 — Synthesize findings
Once the team converges or all hypotheses have been tested:
Debug Investigation Report
Bug: [description]
Root cause: [the winning hypothesis with evidence]
Confidence: High / Medium / Low
Evidence summary
| Hypothesis | Verdict | Key evidence |
|---|
| [A] | Confirmed / Eliminated / Inconclusive | [summary] |
| [B] | Confirmed / Eliminated / Inconclusive | [summary] |
| [C] | Confirmed / Eliminated / Inconclusive | [summary] |
Root cause analysis
- What: [precise description of the bug]
- Where: [file:line or component]
- Why: [how the bug was introduced]
- When: [when it started — commit, deploy, config change]
Recommended fix
- [Step-by-step fix description]
- [Files to modify]
- [Tests to add to prevent regression]
What was ruled out
- [Eliminated hypotheses and why — this prevents re-investigation]
Step 6 — Offer to fix
Investigation complete. Root cause identified.
Options:
• "fix it" — I'll implement the fix using TDD (/implement)
• "team fix" — I'll create a team to fix and add regression tests (/team-implement)
• "just the report" — Take the findings and fix manually
Step 7 — Clean up
Ask all investigators to shut down, then clean up the team.
When to use /team-debug vs direct debugging
| Situation | Use |
|---|
| Obvious bug with clear stack trace | Debug directly |
| Multiple plausible root causes | /team-debug |
| Intermittent or hard-to-reproduce bug | /team-debug |
| Production incident needing fast resolution | /team-debug |
| Simple typo or config error | Debug directly |
| Cross-system or cross-service issue | /team-debug |
Gotchas
These are common failure modes during parallel debugging. Watch for them:
- Confirmation bias. Investigators find evidence that supports their hypothesis and stop looking. Every investigator must actively seek evidence AGAINST their theory — finding disconfirming evidence is more valuable than finding confirming evidence.
- Hypotheses that aren't testable. "Maybe it's a timing issue" is not a hypothesis. "The race condition between the auth middleware and the session store causes a null user when requests arrive within 10ms of each other" is testable. If you can't describe how to prove it wrong, it's not a hypothesis.
- Investigators going down rabbit holes. If an investigator has been working for 20+ messages without finding evidence either way, their hypothesis is too vague or untestable. Redirect them or eliminate the hypothesis.
- All hypotheses eliminated, no new ones formed. This means the symptoms were misunderstood. Go back to Step 1, re-read the error with fresh eyes, and form new hypotheses based on what was ruled out.
- Investigators modifying code. Debug investigators observe and analyze — they do NOT write fixes. If an investigator starts patching code to "test if this fixes it," stop them. The fix comes after the investigation.
Important constraints
- Evidence over opinion. Every claim must cite specific code, logs, or behavior.
- Investigators do NOT fix the bug. They investigate and report. Fixing is a separate step.
- Adversarial collaboration is key. Investigators must try to disprove each other, not just confirm their own theory.
- Abandon disproven hypotheses. Don't waste time defending a theory that evidence contradicts.
- Clean up the team when done. Do not leave orphaned teammates.
