Swarm Debug

Swarm Debugging

Overview

Parallel adversarial investigation. Multiple teammates test competing hypotheses simultaneously, actively trying to disprove each other. Converges on root cause faster by fighting anchoring bias.

Core principle: One investigator anchors on their first theory. A team of investigators who must disprove each other cannot.

This skill extends the groundwork:debug workflow. Phases 1-2 and 4-5 follow that skill exactly. Phase 3 (ISOLATE) is replaced by parallel swarm investigation using Claude Code agent teams.

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low 5) | Prioritize. More teammates means more noise, not more signal. | | Too few hypotheses (<3) | If there's only one plausible theory, use standard debugging. | | Teammates not challenging each other | Re-prompt with explicit adversarial instructions. Agreement without challenge is suspect. | | Calling convergence too early | Wait for active disproof attempts. "No one disagreed" is not convergence. | | Teammates editing code | Enforce read-only. Code conflicts between teammates waste more time than they save. | | Ignoring dissenting evidence | Record it. If one teammate found contradicting evidence, the root cause analysis must address it. | | Skipping cleanup | Remove all temporary logging/instrumentation before Phase 4. |

Graceful Fallback

If agent teams is not available (feature not enabled or not supported):

1. Detect the absence at the start of Phase 3
2. Notify the user: "Agent teams feature is not enabled. To use swarm debugging, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true. Falling back to sequential debugging."
3. Invoke Skill(skill="groundwork:debug") and continue with its standard Phase 3 (sequential hypothesis testing)
4. The debug journal should note that swarm was attempted but unavailable

Final Rule

Parallel investigation → Adversarial disproof → Convergence → Fix with failing test → Verify
Otherwise → you're just running multiple guessers in parallel

The swarm's power is adversarial challenge, not parallel agreement. If your teammates aren't trying to prove each other wrong, you're not swarm debugging.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: etr
• Source: etr/groundwork
• License: MIT

Install and usage instructions live in the source repository linked above.