Debugging

Debugging

Systematic approach to root cause analysis and debugging.

When to Use

• Encountering errors or exceptions
• Test failures that need investigation
• Unexpected behavior in code
• Stack traces or error messages
• Code behaving differently than expected
• Performance issues or bugs

Core Principles

• Evidence-based: Base diagnosis on error messages, logs, and reproducible steps
• Systematic: Follow structured debugging process
• Minimal fixes: Implement smallest change that resolves issue
• Verify solutions: Confirm fix works and doesn't introduce regressions

Debugging Process

Follow systematic debugging process: 1. Capture error information (message, stack trace, logs, environment) 2. Identify reproduction steps (minimal steps, conditions, edge cases) 3. Isolate failure location (function/module, recent changes, dependencies) 4. Form and test hypotheses (evidence-based, systematic testing, debug logging) 5. Implement minimal fix (smallest change, preserve behavior, follow patterns) 6. Verify solution (issue resolved, no regressions, tests pass)

See references/root-cause-analysis.md for detailed methods.

Strategic Debug Logging

Add debug logging to entry/exit points, state transitions, conditional branches, external API calls, and data transformations. Remove after issue resolved unless it provides ongoing value.

Error Pattern Recognition

Common patterns: null/undefined errors, type errors, timing issues, state corruption, configuration issues. See references/error-patterns.md for detailed patterns and solutions.

Integration

After fixing:

• Verify CI passes (types, tests, lint)
• Stage atomic changes (fix + tests)
• Suggest semantic commit message
• Confirm with user before committing

References

For detailed guidance, see:

• references/root-cause-analysis.md - Systematic analysis methods
• references/error-patterns.md - Common error patterns and solutions
• references/debugging-tools.md - Debugging tools and techniques

Debugging Tools

Tools and techniques for effective debugging.

Logging

Strategic logging:

• Entry/exit points
• State transitions
• Conditional branches
• External calls
• Error conditions

Log levels:

• Debug: Detailed information
• Info: General flow
• Warn: Potential issues
• Error: Actual errors

Debuggers

Language-specific:

• Node.js: node --inspect, Chrome DevTools
• Python: pdb, ipdb, IDE debuggers
• TypeScript: Source maps with debuggers

Usage:

• Set breakpoints at suspect locations
• Step through code execution
• Inspect variable values
• Watch expressions

Testing

Unit tests:

• Isolate suspect code
• Test edge cases
• Verify assumptions
• Reproduce issues

Integration tests:

• Test component interactions
• Verify data flow
• Check external dependencies

Profiling

Performance issues:

• CPU profiling
• Memory profiling
• Network profiling
• Identify bottlenecks

Code Analysis

Static analysis:

• Type checkers
• Linters
• Security scanners
• Complexity analysis

Dynamic analysis:

• Runtime type checking
• Assertions
• Contract validation

Best Practices

1. Reproduce first: Ensure you can reproduce the issue 2. Isolate: Narrow down to minimal case 3. Log strategically: Add logging to understand flow 4. Test hypotheses: Verify assumptions 5. Fix root cause: Not just symptoms 6. Verify fix: Confirm solution works 7. Prevent recurrence: Add tests or guards

Error Patterns

Common error patterns and their typical causes.

Null/Undefined Errors

Symptoms:

• TypeError: Cannot read property 'x' of undefined
• TypeError: Cannot read property 'x' of null

Common Causes:

• Missing null checks
• Uninitialized variables
• Failed API calls without error handling
• Missing default values

Solutions:

• Add null/undefined checks
• Use optional chaining (?.)
• Provide default values
• Handle API errors properly

Type Errors

Symptoms:

• TypeError: x is not a function
• Type mismatches in TypeScript/Python

Common Causes:

• Incorrect type assumptions
• Missing type guards
• Type coercion issues
• API contract changes

Solutions:

• Add type guards
• Verify types at boundaries
• Use type assertions carefully
• Check API contracts

Timing Issues

Symptoms:

• Race conditions
• Async/await problems
• Order-dependent failures

Common Causes:

• Missing await
• Incorrect async flow
• Shared mutable state
• Event ordering issues

Solutions:

• Ensure proper await usage
• Use proper async patterns
• Avoid shared mutable state
• Add synchronization if needed

State Corruption

Symptoms:

• Unexpected state values
• Inconsistent behavior
• Side effects

Common Causes:

• Mutating shared state
• Missing state updates
• Incorrect state management
• Side effects in wrong places

Solutions:

• Use immutable patterns
• Centralize state management
• Isolate side effects
• Add state validation

Configuration Issues

Symptoms:

• Missing environment variables
• Incorrect settings
• Feature flags not working

Common Causes:

• Missing .env files
• Incorrect variable names
• Default values not set
• Configuration not loaded

Solutions:

• Verify environment setup
• Check configuration loading
• Provide sensible defaults
• Validate configuration

Root Cause Analysis

Systematic methods for identifying root causes of issues.

Analysis Framework

1. Symptom Analysis

Understand the problem:

• What is the actual vs expected behavior?
• When does it occur?
• What conditions trigger it?
• Is it reproducible?

2. Hypothesis Generation

Based on evidence, generate hypotheses:

• What could cause this symptom?
• What changed recently?
• What dependencies are involved?
• What patterns match known issues?

3. Hypothesis Testing

Test each hypothesis:

• Add logging to verify assumptions
• Create minimal test cases
• Isolate variables
• Check each dependency

4. Root Cause Identification

Identify the underlying cause:

• Not just the immediate error
• Why did the error occur?
• What allowed it to happen?
• What prevents it from being caught?

5. Solution Design

Design fix that:

• Addresses root cause, not just symptom
• Prevents recurrence
• Maintains existing behavior
• Follows codebase patterns

Common Root Causes

Code Issues:

• Logic errors
• Type mismatches
• Missing error handling
• Incorrect assumptions

State Issues:

• Uninitialized state
• State corruption
• Race conditions
• Stale state

Configuration Issues:

• Missing environment variables
• Incorrect settings
• Version mismatches
• Dependency issues

Architecture Issues:

• Tight coupling
• Missing abstractions
• Incorrect data flow
• Resource leaks

Verification

After identifying root cause: 1. Verify hypothesis with evidence 2. Test fix in isolation 3. Confirm fix resolves issue 4. Check for regressions 5. Update tests if needed