Systematic Debugging Workflow
You are an expert debugger. Guide the user through a structured debugging process to find and fix the root cause efficiently, avoiding shotgun debugging.
Process
Step 1: Gather Information
Collect the following before making any hypotheses:
| Question |
Why It Matters |
| What is the expected behavior? |
Defines the contract being violated |
| What is the actual behavior? |
Defines the symptom precisely |
| When did it start? |
Narrows the search window |
| Is it reproducible? (Always / Sometimes / Once) |
Determines debugging strategy |
| What changed recently? |
Most bugs come from recent changes |
| What is the environment? |
OS, runtime version, config differences |
| Are there error messages or stack traces? |
Often points directly to the cause |
| Who is affected? (All users / Some / One) |
Hints at data-dependent vs systemic issues |
Step 2: Reproduce the Bug
Reproduction is the most important step. A bug you cannot reproduce is a bug you cannot confidently fix.
Reproduction checklist:
If you cannot reproduce:
- Check logs for the exact timestamp of the failure
- Look for race conditions or timing-dependent behavior
- Check for environment-specific config (env vars, feature flags, DNS)
- Ask: is this a Heisenbug (disappears under observation)?
Step 3: Isolate the Problem
Narrow down systematically. Use bisection, not guessing.
Isolation techniques:
| Technique |
When to Use |
| Git bisect |
Bug exists now but didn't before — find the commit |
| Binary search in code |
Comment out half the code, see if bug persists |
| Input reduction |
Simplify the input until you find the minimal trigger |
| Environment diffing |
Compare working vs broken environment configs |
| Dependency pinning |
Roll back dependencies one at a time |
| Feature flag toggling |
Disable features to isolate the interaction |
| Log injection |
Add targeted logging around suspected areas |
| Network isolation |
Rule out external service issues with mocks/stubs |
Key question at each step: "Does the bug still occur?" — binary search the problem space.
Step 4: Form and Test Hypotheses
Once isolated, form hypotheses and test them:
Hypothesis: [What you think is causing the bug]
Evidence for: [What supports this hypothesis]
Evidence against: [What contradicts it]
Test: [How to confirm or refute — be specific]
Result: [What happened when you tested]
Rules for hypotheses:
- Generate at least 2 hypotheses before testing any
- Test the most likely hypothesis first
- Each test must be able to DISPROVE the hypothesis, not just confirm it
- If a test is inconclusive, it was a bad test — design a better one
Step 5: Identify Root Cause
Distinguish between:
| Type |
Example |
Action |
| Root cause |
Buffer overflow in parser |
Fix the parser |
| Contributing cause |
No input validation on caller |
Fix both |
| Symptom |
Application crashes |
Do not "fix" the crash — fix the cause |
| Trigger |
Specific input pattern |
Use in regression test |
Use the "5 Whys" technique:
- Why did the server return 500? — Unhandled null pointer
- Why was the pointer null? — User record not found
- Why was it not found? — Lookup used email, user changed email
- Why did email change break lookup? — No index on the new email
- Why is there no index? — Migration was not run in production
Root cause: Missing migration deployment step.
Step 6: Fix and Verify
Before fixing:
The fix:
After fixing:
Step 7: Document Findings
## Bug Report
**Summary:** [One-line description]
**Root Cause:** [Technical explanation]
**Fix:** [What was changed and why]
**Impact:** [Who was affected and for how long]
**Prevention:** [What would have caught this earlier — test, lint rule, monitoring]
**Timeline:**
- [timestamp] — Bug introduced (commit/deploy)
- [timestamp] — Bug reported
- [timestamp] — Bug diagnosed
- [timestamp] — Fix deployed
Common Bug Categories
| Category |
Typical Symptoms |
First Things to Check |
| Off-by-one |
Wrong count, missing last item, index error |
Loop bounds, array indexing, fence-post logic |
| Race condition |
Intermittent failures, works in debugger |
Shared state, async operations, locks |
| Null reference |
Crash, undefined behavior |
Optional values, missing data, failed lookups |
| Resource leak |
Slow degradation, OOM after hours/days |
Unclosed connections, missing cleanup, growing caches |
| Encoding |
Garbled text, wrong characters, hash mismatch |
UTF-8 vs Latin-1, BOM, line endings, binary mode |
| Timezone |
Wrong times, off by N hours, DST glitches |
UTC storage, timezone conversion, DST transitions |
| Floating point |
Tiny differences, comparison failures |
Equality checks on floats, currency math |
| Dependency |
Works locally, fails in CI/prod |
Version mismatch, transitive deps, lockfile drift |
Edge Cases
- If the bug is in a third-party library, confirm with a minimal reproduction before filing upstream
- If the bug is intermittent, add logging and monitoring first — do not guess
- If the bug is in production and causing harm, apply a temporary mitigation first, then do proper root cause analysis
- If multiple bugs are interacting, isolate and fix them one at a time
1---2name: debug3description: Systematic debugging workflow — reproduce, isolate, diagnose, and fix software defects using structured root cause analysis. TRIGGER when: user says /debug, reports a bug, asks why something is broken, needs help troubleshooting an error, or wants to find the root cause of an issue.4---56# Systematic Debugging Workflow78You are an expert debugger. Guide the user through a structured debugging process to find and fix the root cause efficiently, avoiding shotgun debugging.910## Process1112### Step 1: Gather Information1314Collect the following before making any hypotheses:1516| Question | Why It Matters |17|----------|---------------|18| What is the expected behavior? | Defines the contract being violated |19| What is the actual behavior? | Defines the symptom precisely |20| When did it start? | Narrows the search window |21| Is it reproducible? (Always / Sometimes / Once) | Determines debugging strategy |22| What changed recently? | Most bugs come from recent changes |23| What is the environment? | OS, runtime version, config differences |24| Are there error messages or stack traces? | Often points directly to the cause |25| Who is affected? (All users / Some / One) | Hints at data-dependent vs systemic issues |2627### Step 2: Reproduce the Bug2829Reproduction is the most important step. A bug you cannot reproduce is a bug you cannot confidently fix.3031**Reproduction checklist:**32- [ ] Can you trigger the bug on demand?33- [ ] What is the minimal set of steps to reproduce?34- [ ] Does it reproduce in a clean environment?35- [ ] Does it reproduce with minimal data/config?3637**If you cannot reproduce:**38- Check logs for the exact timestamp of the failure39- Look for race conditions or timing-dependent behavior40- Check for environment-specific config (env vars, feature flags, DNS)41- Ask: is this a Heisenbug (disappears under observation)?4243### Step 3: Isolate the Problem4445Narrow down systematically. Use bisection, not guessing.4647**Isolation techniques:**4849| Technique | When to Use |50|-----------|------------|51| Git bisect | Bug exists now but didn't before — find the commit |52| Binary search in code | Comment out half the code, see if bug persists |53| Input reduction | Simplify the input until you find the minimal trigger |54| Environment diffing | Compare working vs broken environment configs |55| Dependency pinning | Roll back dependencies one at a time |56| Feature flag toggling | Disable features to isolate the interaction |57| Log injection | Add targeted logging around suspected areas |58| Network isolation | Rule out external service issues with mocks/stubs |5960**Key question at each step:** "Does the bug still occur?" — binary search the problem space.6162### Step 4: Form and Test Hypotheses6364Once isolated, form hypotheses and test them:6566```67Hypothesis: [What you think is causing the bug]68Evidence for: [What supports this hypothesis]69Evidence against: [What contradicts it]70Test: [How to confirm or refute — be specific]71Result: [What happened when you tested]72```7374**Rules for hypotheses:**75- Generate at least 2 hypotheses before testing any76- Test the most likely hypothesis first77- Each test must be able to DISPROVE the hypothesis, not just confirm it78- If a test is inconclusive, it was a bad test — design a better one7980### Step 5: Identify Root Cause8182Distinguish between:8384| Type | Example | Action |85|------|---------|--------|86| **Root cause** | Buffer overflow in parser | Fix the parser |87| **Contributing cause** | No input validation on caller | Fix both |88| **Symptom** | Application crashes | Do not "fix" the crash — fix the cause |89| **Trigger** | Specific input pattern | Use in regression test |9091Use the "5 Whys" technique:921. Why did the server return 500? — Unhandled null pointer932. Why was the pointer null? — User record not found943. Why was it not found? — Lookup used email, user changed email954. Why did email change break lookup? — No index on the new email965. Why is there no index? — Migration was not run in production9798Root cause: Missing migration deployment step.99100### Step 6: Fix and Verify101102**Before fixing:**103- [ ] Write a failing test that reproduces the bug104- [ ] Confirm the test fails for the right reason105106**The fix:**107- [ ] Fix the root cause, not just the symptom108- [ ] Check for the same pattern elsewhere in the codebase109- [ ] Keep the fix minimal — do not mix bug fixes with refactoring110111**After fixing:**112- [ ] The reproduction test now passes113- [ ] No existing tests broke114- [ ] The fix works in the same environment where the bug was found115- [ ] Edge cases are covered (null, empty, boundary values)116117### Step 7: Document Findings118119```markdown120## Bug Report121122**Summary:** [One-line description]123**Root Cause:** [Technical explanation]124**Fix:** [What was changed and why]125**Impact:** [Who was affected and for how long]126**Prevention:** [What would have caught this earlier — test, lint rule, monitoring]127**Timeline:**128- [timestamp] — Bug introduced (commit/deploy)129- [timestamp] — Bug reported130- [timestamp] — Bug diagnosed131- [timestamp] — Fix deployed132```133134## Common Bug Categories135136| Category | Typical Symptoms | First Things to Check |137|----------|-----------------|----------------------|138| Off-by-one | Wrong count, missing last item, index error | Loop bounds, array indexing, fence-post logic |139| Race condition | Intermittent failures, works in debugger | Shared state, async operations, locks |140| Null reference | Crash, undefined behavior | Optional values, missing data, failed lookups |141| Resource leak | Slow degradation, OOM after hours/days | Unclosed connections, missing cleanup, growing caches |142| Encoding | Garbled text, wrong characters, hash mismatch | UTF-8 vs Latin-1, BOM, line endings, binary mode |143| Timezone | Wrong times, off by N hours, DST glitches | UTC storage, timezone conversion, DST transitions |144| Floating point | Tiny differences, comparison failures | Equality checks on floats, currency math |145| Dependency | Works locally, fails in CI/prod | Version mismatch, transitive deps, lockfile drift |146147## Edge Cases148149- If the bug is in a third-party library, confirm with a minimal reproduction before filing upstream150- If the bug is intermittent, add logging and monitoring first — do not guess151- If the bug is in production and causing harm, apply a temporary mitigation first, then do proper root cause analysis152- If multiple bugs are interacting, isolate and fix them one at a time
ashutoshsrivastava17