Systematic Debugging
Always investigate root cause before proposing fixes.
Core Rule
No fixes without root-cause investigation.
Workflow
- Reproduce: capture exact steps and error output.
- Localize: find the smallest failing scope (file, test, input).
- Trace: follow data and control flow to the first wrong state.
- Fix: smallest change that addresses the root cause.
- Verify: re-run the failing test/flow and any related checks.
When stuck
- Add diagnostic logging at component boundaries.
- Create a minimal reproduction case.
- Use bisect to isolate the introduction point.
References
- Root-cause tracing:
references/root-cause-tracing.md - Defense-in-depth fixes:
references/defense-in-depth.md - Condition-based waiting:
references/condition-based-waiting.md - Extended examples:
references/examples.md