systematic-debugging
starsforks
How to install systematic-debugging?
one-man-company/skills-contextmanager/systematic-debugging
$npx -y skills add One-Man-Company/Skills-ContextManager --skill systematic-debugging4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
SKILL.md
| 1 | # Systematic Debugging |
| 2 | |
| 3 | > Source: obra/superpowers |
| 4 | |
| 5 | ## Overview |
| 6 | This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving. |
| 7 | |
| 8 | ## 4-Phase Debugging Process |
| 9 | |
| 10 | ### Phase 1: Reproduce |
| 11 | Before fixing, reliably reproduce the issue. |
| 12 | |
| 13 | ```markdown |
| 14 | ## Reproduction Steps |
| 15 | 1. [Exact step to reproduce] |
| 16 | 2. [Next step] |
| 17 | 3. [Expected vs actual result] |
| 18 | |
| 19 | ## Reproduction Rate |
| 20 | - [ ] Always (100%) |
| 21 | - [ ] Often (50-90%) |
| 22 | - [ ] Sometimes (10-50%) |
| 23 | - [ ] Rare (<10%) |
| 24 | ``` |
| 25 | |
| 26 | ### Phase 2: Isolate |
| 27 | Narrow down the source. |
| 28 | |
| 29 | ```markdown |
| 30 | ## Isolation Questions |
| 31 | - When did this start happening? |
| 32 | - What changed recently? |
| 33 | - Does it happen in all environments? |
| 34 | - Can we reproduce with minimal code? |
| 35 | - What's the smallest change that triggers it? |
| 36 | ``` |
| 37 | |
| 38 | ### Phase 3: Understand |
| 39 | Find the root cause, not just symptoms. |
| 40 | |
| 41 | ```markdown |
| 42 | ## Root Cause Analysis |
| 43 | ### The 5 Whys |
| 44 | 1. Why: [First observation] |
| 45 | 2. Why: [Deeper reason] |
| 46 | 3. Why: [Still deeper] |
| 47 | 4. Why: [Getting closer] |
| 48 | 5. Why: [Root cause] |
| 49 | ``` |
| 50 | |
| 51 | ### Phase 4: Fix & Verify |
| 52 | Fix and verify it's truly fixed. |
| 53 | |
| 54 | ```markdown |
| 55 | ## Fix Verification |
| 56 | - [ ] Bug no longer reproduces |
| 57 | - [ ] Related functionality still works |
| 58 | - [ ] No new issues introduced |
| 59 | - [ ] Test added to prevent regression |
| 60 | ``` |
| 61 | |
| 62 | ## Debugging Checklist |
| 63 | |
| 64 | ```markdown |
| 65 | ## Before Starting |
| 66 | - [ ] Can reproduce consistently |
| 67 | - [ ] Have minimal reproduction case |
| 68 | - [ ] Understand expected behavior |
| 69 | |
| 70 | ## During Investigation |
| 71 | - [ ] Check recent changes (git log) |
| 72 | - [ ] Check logs for errors |
| 73 | - [ ] Add logging if needed |
| 74 | - [ ] Use debugger/breakpoints |
| 75 | |
| 76 | ## After Fix |
| 77 | - [ ] Root cause documented |
| 78 | - [ ] Fix verified |
| 79 | - [ ] Regression test added |
| 80 | - [ ] Similar code checked |
| 81 | ``` |
| 82 | |
| 83 | ## Common Debugging Commands |
| 84 | |
| 85 | ```bash |
| 86 | # Recent changes |
| 87 | git log --oneline -20 |
| 88 | git diff HEAD~5 |
| 89 | |
| 90 | # Search for pattern |
| 91 | grep -r "errorPattern" --include="*.ts" |
| 92 | |
| 93 | # Check logs |
| 94 | pm2 logs app-name --err --lines 100 |
| 95 | ``` |
| 96 | |
| 97 | ## Anti-Patterns |
| 98 | |
| 99 | ❌ **Random changes** - "Maybe if I change this..." |
| 100 | ❌ **Ignoring evidence** - "That can't be the cause" |
| 101 | ❌ **Assuming** - "It must be X" without proof |
| 102 | ❌ **Not reproducing first** - Fixing blindly |
| 103 | ❌ **Stopping at symptoms** - Not finding root cause |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
