---
name: debugging
description: Apply systematic debugging methodology. Use when investigating bugs, unexpected behavior, or when user reports issues. Auto-apply when conversation includes "bug", "broken", "not working", "wrong", "glitch", "flickering".
---

# Debugging Skill

## Core Principle

**Automate first, ask questions never.** If you can write a test to verify behavior, do that instead of asking the user to manually check something.

## Debugging Decision Tree

```
Bug reported
    │
    ▼
Can I reproduce in a test?
    │
    ├─ YES → Write failing test first
    │         │
    │         ▼
    │    Does test fail?
    │         │
    │         ├─ YES → Debug the logic
    │         │
    │         └─ NO → Bug is in rendering/CSS layer
    │
    └─ NO → Need more info from user (specific steps, values)
```

## Systematic Isolation

| Question | Test Strategy |
|----------|---------------|
| Is the calculation correct? | Unit test with known inputs |
| Is the rendering correct? | Integration test, inspect CSS |
| Is it browser-specific? | Playwright test |
| Is it timing-related? | Time progression integration test |
| Is it state-related? | Expose `window.__debug`, inspect values |

## Common Bug Patterns

### 1. CSS Transitions + 60fps React

**Symptom**: Values correct in test, visual is wrong/flickering in browser.

**Cause**: CSS transitions on elements that React updates every frame.

**Detection**:
```bash
# Find transitions on frequently-updated elements
grep -r "transition:" src/ui/*.css
```

**Fix**: Remove CSS transitions from elements in the game loop render path.

### 2. State Not Updating

**Symptom**: UI shows stale data.

**Test**:
```javascript
it('state updates over time', () => {
  const { rerender } = render(<Component time={0} />);
  const value0 = getValue();

  rerender(<Component time={1000} />);
  const value1 = getValue();

  expect(value1).not.toEqual(value0);
});
```

### 3. Calculation Drift

**Symptom**: Values slowly diverge from expected over time.

**Test**:
```javascript
it('no drift over many iterations', () => {
  let state = initialState;
  for (let i = 0; i < 10000; i++) {
    state = update(state, 16); // 16ms per frame
  }
  expect(state.value).toBeCloseTo(expected, 2);
});
```

## Debug State Exposure

For browser inspection, expose state in dev mode:

```javascript
// In game loop
if (import.meta.env.DEV) {
  window.__debug = {
    state: world.setLullState,
    gameTime: world.gameTime,
    computed: { /* derived values */ }
  };
}
```

Then in browser console: `window.__debug.state`

## Anti-Patterns

| Don't Do This | Do This Instead |
|---------------|-----------------|
| Add `console.log`, ask user to check | Write Vitest test |
| Guess at the problem | Systematically isolate with tests |
| Fix symptoms | Find and fix root cause |
| Manual browser debugging | Playwright automation |
| Change code without understanding | Read and understand first |

## Integration with Testing Skill

When debugging, use these test patterns:

1. **Regression test** - Fails without fix, passes with fix
2. **Time progression test** - Simulates frames over time
3. **Edge case test** - Zero, negative, maximum values
4. **Snapshot test** - For complex state objects

## Debugging Checklist

- [ ] Can I write a failing test?
- [ ] Does the test isolate the bug?
- [ ] Have I checked CSS interactions?
- [ ] Have I verified state values?
- [ ] Is there a timing/animation issue?
- [ ] Did I find the root cause (not just symptoms)?