name: debugging
description: Systematic debugging patterns for finding and fixing bugs. Use when troubleshooting errors, unexpected behavior, or performance issues.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Debugging

Systematic approach to finding and fixing bugs.

The Scientific Method for Debugging

1. Observe - What exactly is happening?
2. Hypothesize - What could cause this?
3. Predict - If my hypothesis is correct, what should I see?
4. Test - Check if the prediction holds
5. Conclude - Was I right? Repeat if not.

Step 1: Reproduce the Bug

Before debugging, ensure you can reliably reproduce the issue:
- What are the exact steps?
- What input triggers it?
- Does it happen every time?
- What environment (OS, browser, version)?

If you can't reproduce it, you can't fix it.

Step 2: Isolate the Problem

Binary Search Debugging

1. Find a known "good" state and "bad" state
2. Check the midpoint
3. Narrow down to the failing section
4. Repeat until you find the exact line

Minimal Reproduction

• Remove code until the bug disappears
• Add code back until it reappears
• The last addition is likely the culprit

Step 3: Understand the Root Cause

Don't just fix symptoms. Ask:
- Why does this input cause this output?
- Why wasn't this caught earlier?
- Where else might this pattern exist?

Common Bug Categories

Off-by-One Errors

• Array index out of bounds
• Loop runs one too many/few times
• Fence post problems

Null/Undefined Errors

• Missing null checks
• Async data not yet loaded
• Optional chaining needed

Race Conditions

• Async operations completing out of order
• Shared state modified concurrently
• Missing await/locks

State Bugs

• Stale closures
• Mutation of shared objects
• Cache invalidation issues

Debugging Tools

Console/Print Debugging

console.log('checkpoint 1', { variable });
console.log('checkpoint 2', { anotherVar });

Interactive Debuggers

• Set breakpoints at suspicious lines
• Inspect variable values
• Step through execution

Logging

• Check application logs for errors
• Add temporary verbose logging
• Use structured logging for complex data

Rubber Duck Debugging

Explain the problem out loud (to a rubber duck, or just yourself):
1. What should the code do?
2. What is it actually doing?
3. Walk through line by line

Often, you'll find the bug while explaining.

After Fixing

1. Write a test that would have caught this bug
2. Check for similar bugs elsewhere in the codebase
3. Document if it was a tricky issue
4. Consider if the design could prevent this class of bug