Debugging

Code you designed or wrote is guilty until proven innocent. Your intent doesn't matter — only the code's actual behavior.

This rule applies symmetrically to defensive code. When the user asks "is this even needed?" or "doesn't the library already do that?", run the underlying library/tool with the bad-input case BEFORE explaining why your code defends against it. Often the library already raises the exact exception you're catching — making your validation dead code. Concrete example: redis-py's RedisCluster(load_balancing_strategy="typo") accepts the bad string at construction and only raises on first read. A wrapper-level enum lookup that "fails loudly at startup" sounds defensible — until empirical test shows the wrapper isn't actually fast-failing earlier than the library would in practice. Run it before defending it.

A. Document Current State

• What is the EXACT error message?
• What are the EXACT reproduction steps?
• What is ACTUAL vs EXPECTED output?
• When did this start?

B. Map the System

• Trace execution path from entry point to failure
• Identify all components involved
• Read relevant source files completely (don't skim)
• Note all dependencies, imports, configurations

C. Gather External Knowledge (when needed)

• Search for exact error messages
• Check library/framework docs for intended behavior
• Look for known issues, breaking changes, version quirks

B. Test Each Hypothesis For each:

• What would prove this true?
• What would prove this false?
• Design minimal test
• Document results

C. Eliminate or Confirm Don't proceed until: which hypothesis is supported by evidence? What evidence contradicts others?

1. Design — What is the MINIMAL change that addresses the root cause?
2. Implement — Make the change with verification logging if needed
3. Test — Does the original issue still occur? Run reproduction steps. Check for regressions.

Evidence

[Exact errors, behaviors, outputs observed]

Investigation

[What you checked, found, and ruled out]

Root Cause

[The actual underlying problem + evidence]

Solution

[What you changed and WHY it addresses the root cause]

Verification

[How you confirmed it works and doesn't break anything else]

</output_format>

<language_examples>

### Python — Adding Debug Points
```python
# Temporary debug prints (remove after fixing)
import json
print(f"DEBUG input: {json.dumps(data, indent=2, default=str)}")
print(f"DEBUG result type: {type(result).__name__}, value: {result!r}")

# Using pdb for interactive debugging
import pdb; pdb.set_trace()  # drops into debugger at this line

# pytest debugging — run with -s flag to see prints
# pytest -s -x tests/test_problematic.py::test_specific_case

Python — Minimal Reproduction

# Isolate the bug — strip everything non-essential
def test_reproduce_bug():
    """Minimal reproduction of the issue."""
    # Arrange: minimum state needed
    data = {"key": "value"}

    # Act: the problematic operation
    result = process(data)

    # Assert: what should happen vs what does happen
    assert result == expected_value, f"Got {result!r}, expected {expected_value!r}"

Node.js — Debug Points

// console.debug with structured data
console.debug('DEBUG processOrder:', { orderId, items: items.length, total });

// Using Node.js debugger
debugger; // pause here when running with --inspect

// Run specific test with verbose output
// npx jest --testNamePattern "specific test" --verbose --no-coverage

Node.js — Async Debugging

// Common async bug: unhandled rejection
async function debugAsyncIssue() {
  try {
    const result = await problematicOperation();
    console.debug('result:', result);
  } catch (err) {
    // Log the FULL error including stack
    console.error('FULL ERROR:', err);
    console.error('Stack:', err.stack);
    throw err; // re-throw after logging
  }
}

During investigation:

• Root cause identified with evidence (not just "it works now")
• Fix verified against original reproduction steps
• Adjacent functionality checked for regressions
• Can explain the solution to another developer
• One variable changed at a time (no simultaneous changes)
• Would pass code review scrutiny