systematic-debugging
starsforks
How to install systematic-debugging?
aaddrick/claude-pipeline/systematic-debugging
$npx -y skills add aaddrick/claude-pipeline --skill systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes
SKILL.md
| 1 | # Systematic Debugging |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | Random fixes waste time and create new bugs. Quick patches mask underlying issues. |
| 6 | |
| 7 | **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure. |
| 8 | |
| 9 | **Violating the letter of this process is violating the spirit of debugging.** |
| 10 | |
| 11 | ## The Iron Law |
| 12 | |
| 13 | ``` |
| 14 | NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST |
| 15 | ``` |
| 16 | |
| 17 | If you haven't completed Phase 1, you cannot propose fixes. |
| 18 | |
| 19 | ## When to Use |
| 20 | |
| 21 | Use for ANY technical issue: |
| 22 | - Test failures |
| 23 | - Bugs in production |
| 24 | - Unexpected behavior |
| 25 | - Performance problems |
| 26 | - Build failures |
| 27 | - Integration issues |
| 28 | |
| 29 | **Use this ESPECIALLY when:** |
| 30 | - Under time pressure (emergencies make guessing tempting) |
| 31 | - "Just one quick fix" seems obvious |
| 32 | - You've already tried multiple fixes |
| 33 | - Previous fix didn't work |
| 34 | - You don't fully understand the issue |
| 35 | |
| 36 | **Don't skip when:** |
| 37 | - Issue seems simple (simple bugs have root causes too) |
| 38 | - You're in a hurry (rushing guarantees rework) |
| 39 | - Manager wants it fixed NOW (systematic is faster than thrashing) |
| 40 | |
| 41 | ## The Four Phases |
| 42 | |
| 43 | You MUST complete each phase before proceeding to the next. |
| 44 | |
| 45 | ### Phase 1: Root Cause Investigation |
| 46 | |
| 47 | **BEFORE attempting ANY fix:** |
| 48 | |
| 49 | 1. **Read Error Messages Carefully** |
| 50 | - Don't skip past errors or warnings |
| 51 | - They often contain the exact solution |
| 52 | - Read stack traces completely |
| 53 | - Note line numbers, file paths, error codes |
| 54 | |
| 55 | 2. **Reproduce Consistently** |
| 56 | - Can you trigger it reliably? |
| 57 | - What are the exact steps? |
| 58 | - Does it happen every time? |
| 59 | - If not reproducible → gather more data, don't guess |
| 60 | |
| 61 | 3. **Check Recent Changes** |
| 62 | - What changed that could cause this? |
| 63 | - Git diff, recent commits |
| 64 | - New dependencies, config changes |
| 65 | - Environmental differences |
| 66 | |
| 67 | 4. **Gather Evidence in Multi-Component Systems** |
| 68 | |
| 69 | **WHEN system has multiple components (CI → build → signing, API → service → database):** |
| 70 | |
| 71 | **BEFORE proposing fixes, add diagnostic instrumentation:** |
| 72 | ``` |
| 73 | For EACH component boundary: |
| 74 | - Log what data enters component |
| 75 | - Log what data exits component |
| 76 | - Verify environment/config propagation |
| 77 | - Check state at each layer |
| 78 | |
| 79 | Run once to gather evidence showing WHERE it breaks |
| 80 | THEN analyze evidence to identify failing component |
| 81 | THEN investigate that specific component |
| 82 | ``` |
| 83 | |
| 84 | **Example (multi-layer system):** |
| 85 | ```bash |
| 86 | # Layer 1: Workflow |
| 87 | echo "=== Secrets available in workflow: ===" |
| 88 | echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" |
| 89 | |
| 90 | # Layer 2: Build script |
| 91 | echo "=== Env vars in build script: ===" |
| 92 | env | grep IDENTITY || echo "IDENTITY not in environment" |
| 93 | |
| 94 | # Layer 3: Signing script |
| 95 | echo "=== Keychain state: ===" |
| 96 | security list-keychains |
| 97 | security find-identity -v |
| 98 | |
| 99 | # Layer 4: Actual signing |
| 100 | codesign --sign "$IDENTITY" --verbose=4 "$APP" |
| 101 | ``` |
| 102 | |
| 103 | **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗) |
| 104 | |
| 105 | 5. **Trace Data Flow** |
| 106 | |
| 107 | **WHEN error is deep in call stack:** |
| 108 | |
| 109 | See `root-cause-tracing.md` in this directory for the complete backward tracing technique. |
| 110 | |
| 111 | **Quick version:** |
| 112 | - Where does bad value originate? |
| 113 | - What called this with bad value? |
| 114 | - Keep tracing up until you find the source |
| 115 | - Fix at source, not at symptom |
| 116 | |
| 117 | ### Phase 2: Pattern Analysis |
| 118 | |
| 119 | **Find the pattern before fixing:** |
| 120 | |
| 121 | 1. **Find Working Examples** |
| 122 | - Locate similar working code in same codebase |
| 123 | - What works that's similar to what's broken? |
| 124 | |
| 125 | 2. **Compare Against References** |
| 126 | - If implementing pattern, read reference implementation COMPLETELY |
| 127 | - Don't skim - read every line |
| 128 | - Understand the pattern fully before applying |
| 129 | |
| 130 | 3. **Identify Differences** |
| 131 | - What's different between working and broken? |
| 132 | - List every difference, however small |
| 133 | - Don't assume "that can't matter" |
| 134 | |
| 135 | 4. **Understand Dependencies** |
| 136 | - What other components does this need? |
| 137 | - What settings, config, environment? |
| 138 | - What assumptions does it make? |
| 139 | |
| 140 | ### Phase 3: Hypothesis and Testing |
| 141 | |
| 142 | **Scientific method:** |
| 143 | |
| 144 | 1. **Form Single Hypothesis** |
| 145 | - State clearly: "I think X is the root cause because Y" |
| 146 | - Write it down |
| 147 | - Be specific, not vague |
| 148 | |
| 149 | 2. **Test Minimally** |
| 150 | - Make the SMALLEST possible change to test hypothesis |
| 151 | - One variable at a time |
| 152 | - Don't fix multiple things at once |
| 153 | |
| 154 | 3. **Verify Before Continuing** |
| 155 | - Did it work? Yes → Phase 4 |
| 156 | - Didn't work? Form NEW hypothesis |
| 157 | - DON'T add more fixes on top |
| 158 | |
| 159 | 4. **When You Don't Know** |
| 160 | - Say "I don't understand X" |
| 161 | - Don't pretend to know |
| 162 | - Ask for help |
| 163 | - Research more |
| 164 | |
| 165 | ### Phase 4: Implementation |
| 166 | |
| 167 | **Fix the root cause, not the symptom:** |
| 168 | |
| 169 | 1. **Create Failing Test Case** |
| 170 | - Simplest possible reproduction |
| 171 | - Automated test if possible |
| 172 | - One-off test script if no framework |
| 173 | - MUST have before fixing |
| 174 | - Use the `test-driven-development` skill for writing proper failing tests |
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
