1.7 KiB
1.7 KiB
Debugging Workflow
Purpose
Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.
When to use
- The defect is real but the cause is unclear
- A failing test needs investigation
- The system has inconsistent or environment-specific behavior
- A regression may have multiple plausible causes
Inputs to gather
- Reproduction path or failing signal
- Relevant code paths, logs, traces, state transitions, and recent changes
- Existing tests or ways to validate a hypothesis
- Environment details that may influence behavior
How to work
- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
- Fix the root cause rather than only masking symptoms when feasible.
- Re-run the original failing signal and add regression protection if appropriate.
Output expectations
- Root cause explanation tied to evidence
- Fix or recommended fix approach
- Verification that the original issue is resolved
- Remaining uncertainty, if any
Quality checklist
- The explanation connects cause to symptom clearly.
- The chosen fix addresses the real failure mechanism.
- Verification includes the original failing path.
- Regression protection is considered when the bug is likely to recur.
Handoff notes
- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
- Mention monitoring or follow-up checks if confidence is limited by environment or observability.