deep-debug

Deep Debug - Multi-Agent Investigation

Status: Production Ready Last Updated: 2026-02-03 Dependencies: Chrome MCP tools (optional), debugger agent, code-reviewer agent

---

When to Use

• Going in circles - You've tried multiple fixes but nothing works
• Browser + API interaction bugs - Need to see Network tab, console logs
• Symptoms don't match expectations - Something deeper is wrong
• Complex state management bugs - React hooks, closures, race conditions

Commands

Command	Purpose
/debug	Guided debugging workflow with evidence gathering and parallel investigation

Quick Start

/debug [description of the bug]

Or invoke naturally:

• "I'm stuck on this bug, can you do a deep investigation?"
• "This bug is resisting normal debugging"
• "I need you to really dig into this"

---

The Process

Phase 1: Gather Evidence (Before Hypothesizing)

For browser-related bugs, use Chrome MCP tools:

// Get network requests (look for duplicates, failures, timing)
mcp__claude-in-chrome__read_network_requests

// Get console logs (errors, warnings, debug output)
mcp__claude-in-chrome__read_console_messages

// Get page state
mcp__claude-in-chrome__read_page

For backend bugs, gather:

• Error logs and stack traces
• Request/response payloads
• Database query logs
• Timing information

Phase 2: Launch Parallel Investigation (3 Agents)

Launch these agents simultaneously with the gathered evidence:

Agent 1: Execution Tracer (debugger)

Task(subagent_type="debugger", prompt="""
EVIDENCE: [paste network/console evidence]

Trace the execution path that leads to this bug. Find:
1. Where the bug originates
2. What triggers it
3. The exact line/function causing the issue

Focus on TRACING, not guessing.
""")

Agent 2: Pattern Analyzer (code-reviewer)

Task(subagent_type="code-reviewer", prompt="""
EVIDENCE: [paste evidence]

Review the relevant code for common bug patterns:
- React useCallback/useMemo dependency issues
- Stale closures
- Race conditions
- State update ordering
- Missing error handling

Find patterns that EXPLAIN the evidence.
""")

Agent 3: Entry Point Mapper (Explore)

Task(subagent_type="Explore", prompt="""
EVIDENCE: [paste evidence]

Map all entry points that could trigger this behavior:
- All places [function] is called
- All event handlers involved
- All state updates that affect this

Find if something is being called MULTIPLE TIMES or from UNEXPECTED places.
""")

Phase 3: Cross-Reference Findings

After agents complete, look for:

Signal	Meaning
All 3 agree on root cause	High confidence - fix it
2 agree, 1 different	Investigate the difference
All 3 different	Need more evidence

Phase 4: Verify Fix

After implementing the fix, re-gather the same evidence to confirm:

• Network tab shows expected behavior
• Console has no errors
• State updates correctly

---

Real Example: Duplicate API Calls Bug

Evidence Gathered

Network tab showed 2 fetch requests for the same message.

Parallel Investigation Results

Agent	Finding
debugger	state.messages in useCallback deps causes callback recreation
code-reviewer	Same finding + explained React pattern causing it
Explore	Verified UI layer wasn't double-calling (ruled out)

Root Cause (Consensus)

sendMessage useCallback had state.messages in dependency array. Every state update recreated the callback, causing duplicate calls during React re-renders.

Fix

Use stateRef to access current state without including in dependencies:

const stateRef = useRef(state);
stateRef.current = state;

const sendMessage = useCallback(async (text) => {
  // Use stateRef.current instead of state
  const messages = stateRef.current.messages;
  // ...
}, [/* state.messages removed */]);

---

Common Bug Patterns This Catches

React Hook Issues

• state in useCallback dependencies causing recreation
• Missing dependencies causing stale closures
• useEffect running multiple times

API/Network Issues

• Duplicate requests (visible in Network tab)
• Race conditions between requests
• CORS failures
• Timeout handling

State Management Issues

• State updates not batching correctly
• Optimistic updates conflicting with server response
• Multiple sources of truth

---

Chrome Tools Quick Reference

Tool	Use For
read_network_requests	See all fetch/XHR calls, duplicates, failures
read_console_messages	Errors, warnings, debug logs
read_page	Current DOM state
javascript_tool	Execute debug code in page context

---

Tips for Success

1. Evidence first, hypotheses second - Don't guess until you have concrete data
2. Network tab is gold - Most frontend bugs show symptoms there
3. Parallel agents save time - 3 perspectives at once vs sequential guessing
4. Cross-reference findings - Agreement = confidence
5. Verify with same evidence - Confirm fix with same tools that found bug