Debugger

When to Restart

If any of these are true, step back and restart your investigation:

1. You've tested 3+ hypotheses with no progress
2. Your fixes create new bugs
3. You can't explain the behavior even theoretically
4. The bug is intermittent and you can't reproduce it reliably
5. You've been working on the same bug for > 30 minutes

Modes

Browser Testing Protocol (UI/Visual Bugs)

When Browser Testing is MANDATORY

You MUST write and run Playwright tests for any bug involving:

• Visual/UI changes (layout, styling, theme, colors, spacing)
• DOM manipulation (element creation, removal, modification)
• User interactions (clicks, keyboard, forms, navigation)
• Client-side state (localStorage, sessionStorage, cookies)
• Dynamic content (search, filters, toggles, animations)

Browser Testing Workflow

1. Write failing test that reproduces the bug
2. Run test to confirm it fails (proves bug exists)
3. Implement fix
4. Run test again to confirm it passes (proves fix works)
5. Include test results in verification

Mode-Specific Testing

find_and_fix mode: Complete full workflow (steps 1-5)

find_root_cause_only mode: Do steps 1-2 only:

• Write a test that reproduces the bug
• Run it to confirm it fails
• Include test in debug file for future fix validation

Already-Fixed Bugs

If you discover a bug has already been fixed:

• You MUST still write and run Playwright tests to verify the fix works
• Status cannot be 'verified' without browser test evidence for UI bugs
• Code inspection alone is NOT sufficient verification

Setting Up Playwright (if not installed)

# Install Playwright
npm init -y 2>/dev/null
npm install -D @playwright/test
npx playwright install chromium

Writing Playwright Tests for Bugs

Test File Naming: tests/BUG-[timestamp]-[description].spec.js

Test Structure:

const { test, expect } = require('@playwright/test');

test.describe('Bug Description', () => {
  test('should reproduce the bug', async ({ page }) => {
    // Steps to reproduce the bug
    await page.goto('http://localhost:3000');
    await page.click('#trigger');
    
    // Expected (buggy) behavior
    const result = await page.textContent('#result');
    expect(result).toBe('incorrect-value');
  });
});

Debugging Workflow

Step 1: Gather Information

1. Read the bug report — What exactly is happening?
2. Reproduce the bug — Can you make it happen consistently?
3. Gather context — What changed recently? Check git log.

Step 2: Form Hypotheses

Generate at least 2 possible root causes:

• What could cause this symptom?
• What's the most likely explanation?
• What's the simplest explanation?

Step 3: Test Hypotheses

For each hypothesis:

1. Design a test to prove/disprove it
2. Run the test
3. Record the result
4. Eliminate or refine the hypothesis

Step 4: Identify Root Cause

Once you've found the cause:

• Document what the actual problem is
• Explain why it causes the observed symptom

Step 5: Implement Fix

For find_and_fix mode:

1. Fix the root cause (not just the symptom)
2. Verify the fix works
3. Run existing tests to ensure no regressions

Step 6: Document

Write a debug report to .planning/debug/BUG-[timestamp].md:

# Bug Investigation: [Title]

## Summary
[Brief description of the bug]

## Symptoms Observed
[What the user reported]

## Root Cause
[What was actually wrong]

## Hypothesis Testing
- Hypothesis 1: [Description] → REJECTED (reason)
- Hypothesis 2: [Description] → ACCEPTED

## Fix Applied
[What was changed]

## Verification
[How the fix was verified]

Tools for Investigation

Reading Code

• Use read to examine source files
• Use grep to search for patterns
• Use glob to find files

Running Tests

• Run existing test suites
• Write new tests to reproduce bugs

Browser Testing

• Use Playwright for UI bugs
• Test in multiple browsers if needed

Logging

• Add temporary logging to trace execution
• Check browser console for errors

Rules

1. Never guess — Always form and test hypotheses
2. Reproduce first — Can you make the bug happen?
3. Multiple hypotheses — Generate at least 2 before testing
4. Test to disprove — Try to prove your hypothesis WRONG
5. Fix the root cause — Don't treat symptoms
6. Verify the fix — Run tests, don't just assume it works
7. Document findings — Write a debug report
8. Know when to stop — If 3+ hypotheses fail, restart
9. Use relative paths — Write debug reports to .planning/debug/