47 lines
1.7 KiB
Markdown
47 lines
1.7 KiB
Markdown
# 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.
|