Debug

git log --oneline -10
git diff HEAD~3 --stat

Did a recent commit touch the failing area? If so, read that diff first.

Gather evidence in multi-component systems

If the failure spans multiple components, trace the data flow:

1. Where does the input enter the system?
2. What transformations happen?
3. Where does the output diverge from expected?

Add temporary logging if needed to narrow down the boundary.

Phase 2: Pattern Analysis

Find a working example

Find code that does something similar and works:

# Search for similar patterns

Use Grep/Glob to find analogous code paths, test cases, or previous implementations.

Compare against the reference

What's different between the working version and the broken one? Common differences:

• Missing null/undefined check
• Different argument order
• Missing await/async
• Wrong import path
• Stale cache or state
• Environment variable missing

Understand the dependency chain

Trace what the broken code depends on:

• What does it import?
• What state does it expect?
• What runs before it?
• What external services does it call?

Phase 3: Hypothesis and Test

Form a single hypothesis

Based on evidence from Phases 1-2, state one clear hypothesis:

"The failure occurs because X, which causes Y, resulting in Z."

Test minimally

Make the smallest possible change to test your hypothesis. If the hypothesis is right, the minimal fix should resolve the issue. If wrong, revert and form a new hypothesis.

Do NOT:

• Change multiple things at once
• "Try random fixes and see what sticks"
• Add workarounds without understanding the root cause

Verify before continuing

Run the reproduction again. If the fix works, proceed to Phase 4. If not, go back to Phase 2 with new information.

Phase 4: Implement the Fix

Create a failing test case

Before applying the fix permanently, write a test that captures the bug:

# Test that reproduces the exact failure

This ensures the bug doesn't regress.

Implement a single fix

Apply the minimal fix. One change, one commit. Don't bundle unrelated cleanup.

Verify comprehensively

1. The new test passes
2. The original failure no longer reproduces
3. Existing tests still pass
4. No regressions introduced

If 3+ fix attempts have failed

Stop. Question the architecture:

• Is the mental model of the system wrong?
• Is there a deeper design issue?
• Present findings to the user via AskUserQuestion with options: A) Continue debugging with a different approach B) Escalate — describe the full investigation so far

Parallel Investigation Mode

When you encounter 2+ independent failures (different root causes, different components):

Dispatch one agent per independent failure domain: