Deep Debug - Multi-Agent Investigation Skill

Deep Debug - Multi-Agent Investigation

When to Use

Going in circles -- multiple fix attempts, 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

The Process

Phase 1: Gather Evidence (Before Hypothesizing)

For browser-related bugs, use Chrome MCP tools:

mcp__claude-in-chrome__read_network_requests  // duplicates, failures, timing
mcp__claude-in-chrome__read_console_messages  // errors, warnings, debug output
mcp__claude-in-chrome__read_page              // page state

For backend bugs, gather: error logs, stack traces, request/response payloads, database query logs, timing information.

Phase 2: Launch Parallel Investigation (3 Agents)

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

| 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

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: Network tab showed 2 fetch requests for the same message.

| 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: sendMessage useCallback had state.messages in dependency array. Every state update recreated the callback, causing duplicate calls during re-renders.

Fix:

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

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

Common Bug Patterns

React Hook Issues: state in useCallback dependencies, missing dependencies causing stale closures, useEffect running multiple times.

API/Network Issues: duplicate requests, race conditions, CORS failures, timeout handling.

State Management Issues: updates not batching correctly, optimistic updates conflicting with server response, multiple sources of truth.

Agent Skills: Deep Debug - Multi-Agent Investigation

Install this agent skill to your local

Skill Files