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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: debugging-73description: Root cause analysis and debugging protocols. Use when encountering errors, test failures, unexpected behavior, stack traces, or when code behaves differently than expected. Use when this capability is needed.4---56# Debugging78Systematic approach to root cause analysis and debugging.910## When to Use1112- Encountering errors or exceptions13- Test failures that need investigation14- Unexpected behavior in code15- Stack traces or error messages16- Code behaving differently than expected17- Performance issues or bugs1819## Core Principles2021- **Evidence-based**: Base diagnosis on error messages, logs, and reproducible steps22- **Systematic**: Follow structured debugging process23- **Minimal fixes**: Implement smallest change that resolves issue24- **Verify solutions**: Confirm fix works and doesn't introduce regressions2526## Debugging Process2728Follow 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)3536See `references/root-cause-analysis.md` for detailed methods.3738## Strategic Debug Logging3940Add 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.4142## Error Pattern Recognition4344Common patterns: null/undefined errors, type errors, timing issues, state corruption, configuration issues. See `references/error-patterns.md` for detailed patterns and solutions.4546## Integration4748After fixing:49- Verify CI passes (types, tests, lint)50- Stage atomic changes (fix + tests)51- Suggest semantic commit message52- Confirm with user before committing5354## References5556For detailed guidance, see:57- `references/root-cause-analysis.md` - Systematic analysis methods58- `references/error-patterns.md` - Common error patterns and solutions59- `references/debugging-tools.md` - Debugging tools and techniques6061---62> Converted and distributed by [TomeVault](https://tomevault.io/claim/siviter-xyz) — claim your Tome and manage your conversions.63<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io