Debugging by competing hypotheses (ACH)

--- description: "Debug issues using competing hypotheses with parallel investigation by multiple agents" argument-hint: "<error-description-or-file> [--hypotheses N] [--scope files|module|project]" --- # Team Debug Debug complex issues using the Analysis of Competing Hypotheses (ACH) methodology. Multiple debugger agents investigate different hypotheses in parallel, gathering evidence to confirm or falsify each one. ## Pre-flight Checks 1. Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set 2. Parse $ARGUMENTS: - <error-description-or-file>: description of the bug, error message, or path to a file exhibiting the issue - --hypotheses N: number of hypotheses to generate (default: 3) - --scope: investigation scope : files (specific files), module (module/package), project (entire project) ## Phase 1: Initial Triage 1. Analyze the error description or file: - If file path: read the file, look for obvious issues, collect error context - If error description: search the codebase for related code, error messages, stack traces 2. Identify the symptom clearly: what is failing, when, and how 3. Gather initial context: recent git changes, related tests, configuration ## Phase 2: Hypothesis Generation Generate N hypotheses about the root cause, covering different failure mode categories: 1. Logic Error : Incorrect algorithm, wrong condition, off-by-one, missing edge case 2. Data Issue : Invalid input, type mismatch, null/undefined, encoding problem 3. State Problem : Race condition, stale cache, incorrect initialization, mutation bug 4. Integration Failure : API contract violation, version mismatch, configuration error 5. Resource Issue : Memory leak, connection exhaustion, timeout, disk space 6. Environment : Missing dependency, wrong version, platform-specific behavior Present hypotheses to user: "Generated {N} hypotheses. Spawning investigators..." ## Phase 3: Investigation 1. Use TeamCreate tool to create the team with team_name: "debug-{timestamp}" and description 2. For each hypothesis, use Agent tool to spawn a teammate: - name: investigator-{n} (e.g., "investigator-1") - subagent_type: "agent-teams:team-debugger" - prompt: Include the hypothesis, investigation scope, and relevant context 3. Use TaskCreate for each investigator's task: - Subject: "Investigate hypothesis: {hypothesis summary}" - Description: Full hypothesis statement, scope boundaries, evidence criteria ## Phase 4: Evidence Collection 1. Monitor TaskList for completion 2. As investigators complete, collect their evidence reports 3. Track: "{completed}/{total} investigations complete" ## Phase 5: Arbitration 1. Compare findings across all investigators: - Which hypotheses were confirmed (high confidence)? - Which were falsified (contradicting evidence)? - Which are inconclusive (insufficient evidence)? 2. Rank confirmed hypotheses by: - Confidence level (High > Medium > Low) - Strength of causal chain - Amount of supporting evidence - Absence of contradicting evidence 3. Present root cause analysis: `` ## Debug Report: {error description} ### Root Cause (Most Likely) **Hypothesis**: {description} **Confidence**: {High/Medium/Low} **Evidence**: {summary with file:line citations} **Causal Chain**: {step-by-step from cause to symptom} ### Recommended Fix {specific fix with code changes} ### Other Hypotheses - {hypothesis 2}: {status} : {brief evidence summary} - {hypothesis 3}: {status} : {brief evidence summary} ` ## Phase 6: Cleanup 1. Send shutdown_request to all investigators 2. Call TeamDelete` to remove team resources