Debugging Methodology

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Complete Phase 1 before proposing fixes.

The Four Phases

Phase 1: Root Cause Investigation

1. Read Error Messages Carefully

• Read stack traces completely; note line numbers, file paths, error codes

2. Reproduce Consistently

• Can you trigger it reliably? Exact steps? Minimal reproduction?
• If not reproducible, gather more data -- don't guess

3. Check Recent Changes

• Git diff, recent commits, new dependencies, config changes

4. Gather Evidence (Multi-Component Systems)

# Trace at each component boundary
echo "=== Layer 1: Workflow ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

echo "=== Layer 2: Build script ==="
env | grep IDENTITY || echo "IDENTITY not in environment"

5. Trace Data Flow -- Where does bad value originate? Keep tracing up until you find the source.

Phase 2: Pattern Analysis

1. Find working examples of similar code
2. Compare against references -- list every difference
3. Understand dependencies (settings, config, environment)

Phase 3: Hypothesis and Testing

1. Form Single Hypothesis: "I think X is the root cause because Y"
2. Test Minimally: Smallest possible change, one variable at a time
3. Verify: Worked? -> Phase 4. Didn't? -> NEW hypothesis (don't add more fixes)

Phase 4: Implementation

1. Create Failing Test -- simplest possible reproduction, automated
2. Implement Single Fix -- ONE change at a time
3. Verify -- test passes? No other tests broken?

If 3+ Fixes Failed: Question architecture. STOP and discuss fundamentals.

Debugging Tools

JavaScript/TypeScript

debugger;  // Pause execution
console.table(arrayOfObjects);
console.time('op'); /* code */ console.timeEnd('op');
console.trace();  // Stack trace
performance.mark('start'); /* code */ performance.mark('end');
performance.measure('op', 'start', 'end');

Python

breakpoint()  # Python 3.7+
# Post-mortem
try: risky_operation()
except: import pdb; pdb.post_mortem()
# Profile
import cProfile; cProfile.run('slow_function()', 'stats')

Go

import "runtime/debug"
debug.PrintStack()
// CPU profiling
import "runtime/pprof"
f, _ := os.Create("cpu.prof")
pprof.StartCPUProfile(f)
defer pprof.StopCPUProfile()

Advanced Techniques

Git Bisect

git bisect start
git bisect bad                    # Current is bad
git bisect good v1.0.0            # This was good
git bisect good   # or bad, repeat until found
git bisect reset

Differential Debugging

Patterns by Issue Type

• Intermittent: Add logging with timing, look for race conditions, stress test
• Performance: Profile first, common culprits: N+1, unnecessary re-renders, sync I/O
• Production: Gather evidence (Sentry/logs/metrics), reproduce locally, test fixes in staging

Red Flags -- STOP and Return to Phase 1

• "Quick fix for now, investigate later"
• "Just try changing X and see"
• "I don't fully understand but this might work"
• "One more fix attempt" (when already tried 2+)

Quick Debugging Checklist

• Spelling errors / typos
• Case sensitivity
• Null/undefined values
• Off-by-one errors
• Async timing / race conditions
• Scope issues / type mismatches
• Missing dependencies / env vars
• Cache issues