debug-workflow

name	debug-workflow
description	Hypothesis-driven debugging methodology: systematic investigation, binary search isolation, escalation criteria. Load when debugging complex, elusive, or multi-system bugs.

Debug Workflow

Methodology for deep, systematic debugging of complex issues.

<when_to_use>

• A test fails and the cause isn't immediately obvious
• A specific invocation behaves unexpectedly under certain conditions
• Debugging requires exploring multiple code paths and dependencies
• Standard "read the error, fix the line" approaches have failed </when_to_use>

Phase 1: Isolate & Gather Context

1. Read the failure: test case, error message, stack trace
2. Gather context: understand the codebase around the failure
3. Identify scope: what code paths, dependencies, configs are involved
4. Reproduce: run the specific test or create a minimal reproduction
5. Document initial state: record what you know about failure conditions

Phase 2: Generate Hypotheses

1. List all possible causes (aim for 3-5)
2. Prioritize by likelihood:
   • Code complexity in the area
   • Recent changes (check VCS history)
   • Common patterns for this failure type
   • Unhandled edge cases
3. Select the most likely hypothesis that can be quickly tested

Phase 3: Iterative Investigation

Core loop — repeat until solved:

1. Test hypothesis: add logging, modify code temporarily, run failing test
2. Analyze results: did behavior change? What new information emerged?
3. Refine or pivot: confirmed → drill deeper; refuted → next hypothesis; inconclusive → different approach

Investigation strategies:

• Binary search: isolate which part of the code introduces the issue
• Dependency tracing: follow data flow through function calls
• State inspection: examine variables at key points
• Configuration testing: try different configs/env vars
• Minimal reproduction: strip to smallest failing case

Phase 4: Confirm Root Cause

1. Explain exactly why the failure occurs
2. Trace impact: what else might be affected
3. Document: the cause, why it manifests under these conditions, other risk scenarios

Phase 5: Fix & Verify

1. Design minimal, targeted fix
2. Implement the fix
3. Run the originally failing test — confirm it passes
4. Run broader test suite — confirm no regressions
5. Clean up: remove temporary debugging code

<escalation_criteria> Escalate to a higher-tier agent when:

• The issue is architectural, not a localized bug
• The fix requires design changes beyond your current task scope
• You've exhausted hypotheses without progress after significant investigation
• The issue spans multiple systems that need coordinated changes </escalation_criteria>

<context_management>

• Track hypotheses in a todo list: tested, pending, refuted
• Compress investigation notes as you go to preserve context
• Focus on one issue at a time
• Preserve existing behavior — changes should target the bug, not surrounding code </context_management>