team-debug

/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:

1. Read the error message, stack trace, or bug report
2. Identify the affected code paths
3. Note when it started (recent changes? new deploy? environment change?)
4. 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:

1. Watch for messages between teammates
2. Note when hypotheses are eliminated
3. If all teammates converge on the same root cause, that's a strong signal
4. 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.