debugging

# Debugging Hard Bugs

## Rubber Ducking

Quote code snippets and explain what each chunk *should* do vs *actually* does. Don't assume—verbalize the logic. Discrepancies reveal bugs.

## Code Flow Tracing

Trace data from entry point to failure. At each transformation: what goes in, what comes out? Mark where expectations diverge.

**Failure-prone boundaries:** async, serialization, type coercion, null propagation, state mutations.

## Hypothesis Testing

1. List 3-5 possible causes
2. List 3-5 assumptions you're making
3. Test to eliminate possibilities
4. Repeat until one remains

**Don't** change code hoping it helps—that creates noise.

## Logging

Log at decision points and async boundaries, not everywhere.

**Workflow:**
1. Add targeted logs
2. Have user perform action and report output
3. Diagnose and fix
4. **After user confirms fix works:** remove all added logging

## Agent Investigation

For complex/unfamiliar code sections acting as a blackbox:

- Spawn an Explore agent to trace a specific code path and report back
- Run agents in background while continuing other investigation

**When stuck:** Spawn 2-3 senior-advisor agents in parallel with different perspectives (pragmatist, architect, skeptic).

**Avoid biasing agents:** Pass them relevant file paths and the observed behavior, but *not* your hypotheses or assumptions. Let them form independent conclusions.

## Before Fixing

- [ ] Identified exact failing line(s)?
- [ ] Understand *why* it fails?

If no, keep investigating.

## Related

- [Frontend Debugging](./frontend.md)