debugging

Systematic Debugging

A structured approach to isolating and resolving bugs efficiently, based on proven debugging methodologies.

When to Use This Skill

• Encountering runtime errors
• Test failures
• Unexpected behavior
• Performance issues
• Investigating reported bugs
• Understanding unfamiliar code

Debugging Methodology

Phase 1: Understand the Problem

Before touching code, gather information:

1. Reproduce the Issue

   • Get exact reproduction steps
   • Identify what triggers the bug
   • Note when it started (recent changes?)

2. Define Expected vs Actual

   Expected: User clicks "Start Session" → Session starts, UI shows running state
   Actual: User clicks "Start Session" → Nothing happens, no error in console
   

3. Gather Context

   • Check error messages and stack traces
   • Review recent git commits
   • Check if it worked before (and what changed)

Phase 2: Isolate the Problem

Narrow down the scope systematically:

// Binary search approach to find failing point
async function startSession(outcomeId: string) {
  console.log('[DEBUG] 1. Starting session for:', outcomeId);
  
  const outcome = await getOutcome(outcomeId);
  console.log('[DEBUG] 2. Got outcome:', outcome?.id);
  
  if (!outcome) {
    console.log('[DEBUG] 2a. Outcome not found, returning early');
    return;
  }
  
  const session = await createSession(outcome);
  console.log('[DEBUG] 3. Created session:', session?.id);
  
  await notifyUI(session);
  console.log('[DEBUG] 4. UI notified');
}

Isolation techniques:

• Add strategic logging at entry/exit points
• Check if issue is in frontend, backend, or IPC
• Verify data at each boundary
• Test with minimal reproduction case

Phase 3: Form Hypothesis

Based on evidence, form specific hypotheses:

## Hypothesis Log

### H1: IPC handler not registered
- Evidence: Console shows "invoke" called but no response
- Test: Add logging to main process IPC handler
- Result: ❌ Handler is registered

### H2: Promise not awaited
- Evidence: Function returns before async work completes
- Test: Add await to database call
- Result: ✅ Missing await found!