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:
- Capture error information (message, stack trace, logs, environment)
- Identify reproduction steps (minimal steps, conditions, edge cases)
- Isolate failure location (function/module, recent changes, dependencies)
- Form and test hypotheses (evidence-based, systematic testing, debug logging)
- Implement minimal fix (smallest change, preserve behavior, follow patterns)
- 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 methodsreferences/error-patterns.md - Common error patterns and solutionsreferences/debugging-tools.md - Debugging tools and techniques
1---2name: debugging3description: Root cause analysis and debugging protocols. Use when encountering errors, test failures, unexpected behavior, stack traces, or when code behaves differently than expected.4---5
6# Debugging
7
8Systematic approach to root cause analysis and debugging.
9
10## When to Use
11
12- Encountering errors or exceptions
13- Test failures that need investigation
14- Unexpected behavior in code
15- Stack traces or error messages
16- Code behaving differently than expected
17- Performance issues or bugs
18
19## Core Principles
20
21- **Evidence-based**: Base diagnosis on error messages, logs, and reproducible steps
22- **Systematic**: Follow structured debugging process
23- **Minimal fixes**: Implement smallest change that resolves issue
24- **Verify solutions**: Confirm fix works and doesn't introduce regressions
25
26## Debugging Process
27
28Follow systematic debugging process:
291. Capture error information (message, stack trace, logs, environment)
302. Identify reproduction steps (minimal steps, conditions, edge cases)
313. Isolate failure location (function/module, recent changes, dependencies)
324. Form and test hypotheses (evidence-based, systematic testing, debug logging)
335. Implement minimal fix (smallest change, preserve behavior, follow patterns)
346. Verify solution (issue resolved, no regressions, tests pass)
35
36See `references/root-cause-analysis.md` for detailed methods.
37
38## Strategic Debug Logging
39
40Add 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.
41
42## Error Pattern Recognition
43
44Common patterns: null/undefined errors, type errors, timing issues, state corruption, configuration issues. See `references/error-patterns.md` for detailed patterns and solutions.
45
46## Integration
47
48After fixing:
49- Verify CI passes (types, tests, lint)
50- Stage atomic changes (fix + tests)
51- Suggest semantic commit message
52- Confirm with user before committing
53
54## References
55
56For detailed guidance, see:
57- `references/root-cause-analysis.md` - Systematic analysis methods
58- `references/error-patterns.md` - Common error patterns and solutions
59- `references/debugging-tools.md` - Debugging tools and techniques
siviter-xyz