SKILL.md
9.9 KB查看排版效果| 1 | --- |
| 2 | name: systematic-debugging |
| 3 | description: "遇到 bug、测试失败或异常行为时，在提出修复方案之前先定位根因。Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes." |
| 4 | --- |
| 5 | |
| 6 | # Systematic Debugging |
| 7 | |
| 8 | > 中文说明：这是一个纯指令类技能，不含联网请求，也不会主动写文件或执行脚本；它指导 AI 在改代码之前先做根因调查，再最小化验证修复。附带 3 份参考文档和 1 个辅助脚本，按需阅读或使用。 |
| 9 | |
| 10 | ## Overview |
| 11 | |
| 12 | **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure. |
| 13 | |
| 14 | **Violating the letter of this process is violating the spirit of debugging.** |
| 15 | |
| 16 | ## The Iron Law |
| 17 | |
| 18 | ``` |
| 19 | NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST |
| 20 | ``` |
| 21 | |
| 22 | If you haven't completed Phase 1, you cannot propose fixes. |
| 23 | |
| 24 | ## When to Use |
| 25 | |
| 26 | Use for ANY technical issue: |
| 27 | - Test failures |
| 28 | - Bugs in production |
| 29 | - Unexpected behavior |
| 30 | - Performance problems |
| 31 | - Build failures |
| 32 | - Integration issues |
| 33 | |
| 34 | **Use this ESPECIALLY when:** |
| 35 | - Under time pressure (emergencies make guessing tempting) |
| 36 | - "Just one quick fix" seems obvious |
| 37 | - You've already tried multiple fixes |
| 38 | - Previous fix didn't work |
| 39 | - You don't fully understand the issue |
| 40 | |
| 41 | **Don't skip when:** |
| 42 | - Issue seems simple (simple bugs have root causes too) |
| 43 | - You're in a hurry (rushing guarantees rework) |
| 44 | - Manager wants it fixed NOW (systematic is faster than thrashing) |
| 45 | |
| 46 | ## The Four Phases |
| 47 | |
| 48 | You MUST complete each phase before proceeding to the next. |
| 49 | |
| 50 | ### Phase 1: Root Cause Investigation |
| 51 | |
| 52 | **BEFORE attempting ANY fix:** |
| 53 | |
| 54 | 1. **Read Error Messages Carefully** |
| 55 | - Don't skip past errors or warnings |
| 56 | - They often contain the exact solution |
| 57 | - Read stack traces completely |
| 58 | - Note line numbers, file paths, error codes |
| 59 | |
| 60 | 2. **Reproduce Consistently** |
| 61 | - Can you trigger it reliably? |
| 62 | - What are the exact steps? |
| 63 | - Does it happen every time? |
| 64 | - If not reproducible → gather more data, don't guess |
| 65 | |
| 66 | 3. **Check Recent Changes** |
| 67 | - What changed that could cause this? |
| 68 | - Git diff, recent commits |
| 69 | - New dependencies, config changes |
| 70 | - Environmental differences |
| 71 | |
| 72 | 4. **Gather Evidence in Multi-Component Systems** |
| 73 | |
| 74 | **WHEN system has multiple components (CI → build → signing, API → service → database):** |
| 75 | |
| 76 | **BEFORE proposing fixes, add diagnostic instrumentation:** |
| 77 | ``` |
| 78 | For EACH component boundary: |
| 79 | - Log what data enters component |
| 80 | - Log what data exits component |
| 81 | - Verify environment/config propagation |
| 82 | - Check state at each layer |
| 83 | |
| 84 | Run once to gather evidence showing WHERE it breaks |
| 85 | THEN analyze evidence to identify failing component |
| 86 | THEN investigate that specific component |
| 87 | ``` |
| 88 | |
| 89 | **Example (multi-layer system):** |
| 90 | ```bash |
| 91 | # Layer 1: Workflow |
| 92 | echo "=== Secrets available in workflow: ===" |
| 93 | echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)" |
| 94 | |
| 95 | # Layer 2: Build script |
| 96 | echo "=== Env vars in build script: ===" |
| 97 | printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment" |
| 98 | |
| 99 | # Layer 3: Signing script |
| 100 | echo "=== Keychain state: ===" |
| 101 | security list-keychains |
| 102 | security find-identity -v |
| 103 | |
| 104 | # Layer 4: Actual signing |
| 105 | codesign --sign "$IDENTITY" --verbose=4 "$APP" |
| 106 | ``` |
| 107 | |
| 108 | **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗) |
| 109 | |
| 110 | 5. **Trace Data Flow** |
| 111 | |
| 112 | **WHEN error is deep in call stack:** |
| 113 | |
| 114 | See `root-cause-tracing.md` in this directory for the complete backward tracing technique. |
| 115 | |
| 116 | **Quick version:** |
| 117 | - Where does bad value originate? |
| 118 | - What called this with bad value? |
| 119 | - Keep tracing up until you find the source |
| 120 | - Fix at source, not at symptom |
| 121 | |
| 122 | ### Phase 2: Pattern Analysis |
| 123 | |
| 124 | **Find the pattern before fixing:** |
| 125 | |
| 126 | 1. **Find Working Examples** |
| 127 | - Locate similar working code in same codebase |
| 128 | - What works that's similar to what's broken? |
| 129 | |
| 130 | 2. **Compare Against References** |
| 131 | - If implementing pattern, read reference implementation COMPLETELY |
| 132 | - Don't skim - read every line |
| 133 | - Understand the pattern fully before applying |
| 134 | |
| 135 | 3. **Identify Differences** |
| 136 | - What's different between working and broken? |
| 137 | - List every difference, however small |
| 138 | - Don't assume "that can't matter" |
| 139 | |
| 140 | 4. **Understand Dependencies** |
| 141 | - What other components does this need? |
| 142 | - What settings, config, environment? |
| 143 | - What assumptions does it make? |
| 144 | |
| 145 | ### Phase 3: Hypothesis and Testing |
| 146 | |
| 147 | **Scientific method:** |
| 148 | |
| 149 | 1. **Form Single Hypothesis** |
| 150 | - State clearly: "I think X is the root cause because Y" |
| 151 | - Write it down |
| 152 | - Be specific, not vague |
| 153 | |
| 154 | 2. **Test Minimally** |
| 155 | - Make the SMALLEST possible change to test hypothesis |
| 156 | - One variable at a time |
| 157 | - Don't fix multiple things at once |
| 158 | |
| 159 | 3. **Verify Before Continuing** |
| 160 | - Did it work? Yes → Phase 4 |
| 161 | - Didn't work? Form NEW hypothesis |
| 162 | - DON'T add more fixes on top |
| 163 | |
| 164 | 4. **When You Don't Know** |
| 165 | - Say "I don't understand X" |
| 166 | - Don't pretend to know |
| 167 | - Ask for help |
| 168 | - Research more |
| 169 | |
| 170 | ### Phase 4: Implementation |
| 171 | |
| 172 | **Fix the root cause, not the symptom:** |
| 173 | |
| 174 | 1. **Create Failing Test Case** |
| 175 | - Simplest possible reproduction |
| 176 | - Automated test if possible |
| 177 | - One-off test script if no framework |
| 178 | - MUST have before fixing |
| 179 | - 先写一个能稳定复现的失败测试（TDD 思路） |
| 180 | |
| 181 | 2. **Implement Single Fix** |
| 182 | - Address the root cause identified |
| 183 | - ONE change at a time |
| 184 | - No "while I'm here" improvements |
| 185 | - No bundled refactoring |
| 186 | |
| 187 | 3. **Verify Fix** |
| 188 | - Test passes now? |
| 189 | - No other tests broken? |
| 190 | - Issue actually resolved? |
| 191 | - 在宣布修复完成前，先做一次完整验证 |
| 192 | |
| 193 | 4. **If Fix Doesn't Work** |
| 194 | - STOP |
| 195 | - Count: How many fixes have you tried? |
| 196 | - If < 3: Return to Phase 1, re-analyze with new information |
| 197 | - **If ≥ 3: STOP and question the architecture (step 5 below)** |
| 198 | - DON'T attempt Fix #4 without architectural discussion |
| 199 | |
| 200 | 5. **If 3+ Fixes Failed: Question Architecture** |
| 201 | |
| 202 | **Pattern indicating architectural problem:** |
| 203 | - Each fix reveals new shared state/coupling/problem in different place |
| 204 | - Fixes require "massive refactoring" to implement |
| 205 | - Each fix creates new symptoms elsewhere |
| 206 | |
| 207 | **STOP and question fundamentals:** |
| 208 | - Is this pattern fundamentally sound? |
| 209 | - Are we "sticking with it through sheer inertia"? |
| 210 | - Should we refactor architecture vs. continue fixing symptoms? |
| 211 | |
| 212 | **Discuss with your human partner before attempting more fixes** |
| 213 | |
| 214 | This is NOT a failed hypothesis - this is a wrong architecture. |
| 215 | |
| 216 | ## Red Flags - STOP and Follow Process |
| 217 | |
| 218 | If you catch yourself thinking: |
| 219 | - "Quick fix for now, investigate later" |
| 220 | - "Just try changing X and see if it works" |
| 221 | - "Add multiple changes, run tests" |
| 222 | - "Skip the test, I'll manually verify" |
| 223 | - "It's probably X, let me fix that" |
| 224 | - "I don't fully understand but this might work" |
| 225 | - "Pattern says X but I'll adapt it differently" |
| 226 | - "Here are the main problems: [lists fixes without investigation]" |
| 227 | - Proposing solutions before tracing data flow |
| 228 | - **"One more fix attempt" (when already tried 2+)** |
| 229 | - **Each fix reveals new problem in different place** |
| 230 | |
| 231 | **ALL of these mean: STOP. Return to Phase 1.** |
| 232 | |
| 233 | **If 3+ fixes failed:** Question the architecture (see Phase 4.5) |
| 234 | |
| 235 | ## your human partner's Signals You're Doing It Wrong |
| 236 | |
| 237 | **Watch for these redirections:** |
| 238 | - "Is that not happening?" - You assumed without verifying |
| 239 | - "Will it show us...?" - You should have added evidence gathering |
| 240 | - "Stop guessing" - You're proposing fixes without understanding |
| 241 | - "Ultra-think this" - Question fundamentals, not just symptoms |
| 242 | - "We're stuck?" (frustrated) - Your approach isn't working |
| 243 | |
| 244 | **When you see these:** STOP. Return to Phase 1. |
| 245 | |
| 246 | ## Common Rationalizations |
| 247 | |
| 248 | | Excuse | Reality | |
| 249 | |--------|---------| |
| 250 | | "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. | |
| 251 | | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. | |
| 252 | | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | |
| 253 | | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. | |
| 254 | | "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. | |
| 255 | | "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. | |
| 256 | | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. | |
| 257 | | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. | |
| 258 | |
| 259 | ## Quick Reference |
| 260 | |
| 261 | | Phase | Key Activities | Success Criteria | |
| 262 | |-------|---------------|------------------| |
| 263 | | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | |
| 264 | | **2. Pattern** | Find working examples, compare | Identify differences | |
| 265 | | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis | |
| 266 | | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass | |
| 267 | |
| 268 | ## When Process Reveals "No Root Cause" |
| 269 | |
| 270 | If systematic investigation reveals issue is truly environmental, timing-dependent, or external: |
| 271 | |
| 272 | 1. You've completed the process |
| 273 | 2. Document what you investigated |
| 274 | 3. Implement appropriate handling (retry, timeout, error message) |
| 275 | 4. Add monitoring/logging for future investigation |
| 276 | |
| 277 | **But:** 95% of "no root cause" cases are incomplete investigation. |
| 278 | |
| 279 | ## Supporting Techniques |
| 280 | |
| 281 | These techniques are part of systematic debugging and available in this directory: |
| 282 | |
| 283 | - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger |
| 284 | - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause |
| 285 | - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
