davila7--claude-code-templates
wehub-resource-sync
1 行
10 KiB
JSON
1 行
10 KiB
JSON
{"content": "---\nname: systematic-debugging\ndescription: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes\n---\n\n# Systematic Debugging\n\n## Overview\n\nRandom fixes waste time and create new bugs. Quick patches mask underlying issues.\n\n**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.\n\n**Violating the letter of this process is violating the spirit of debugging.**\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\nIf you haven't completed Phase 1, you cannot propose fixes.\n\n## When to Use\n\nUse for ANY technical issue:\n- Test failures\n- Bugs in production\n- Unexpected behavior\n- Performance problems\n- Build failures\n- Integration issues\n\n**Use this ESPECIALLY when:**\n- Under time pressure (emergencies make guessing tempting)\n- \"Just one quick fix\" seems obvious\n- You've already tried multiple fixes\n- Previous fix didn't work\n- You don't fully understand the issue\n\n**Don't skip when:**\n- Issue seems simple (simple bugs have root causes too)\n- You're in a hurry (rushing guarantees rework)\n- Manager wants it fixed NOW (systematic is faster than thrashing)\n\n## The Four Phases\n\nYou MUST complete each phase before proceeding to the next.\n\n### Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n1. **Read Error Messages Carefully**\n - Don't skip past errors or warnings\n - They often contain the exact solution\n - Read stack traces completely\n - Note line numbers, file paths, error codes\n\n2. **Reproduce Consistently**\n - Can you trigger it reliably?\n - What are the exact steps?\n - Does it happen every time?\n - If not reproducible → gather more data, don't guess\n\n3. **Check Recent Changes**\n - What changed that could cause this?\n - Git diff, recent commits\n - New dependencies, config changes\n - Environmental differences\n\n4. **Gather Evidence in Multi-Component Systems**\n\n **WHEN system has multiple components (CI → build → signing, API → service → database):**\n\n **BEFORE proposing fixes, add diagnostic instrumentation:**\n ```\n For EACH component boundary:\n - Log what data enters component\n - Log what data exits component\n - Verify environment/config propagation\n - Check state at each layer\n\n Run once to gather evidence showing WHERE it breaks\n THEN analyze evidence to identify failing component\n THEN investigate that specific component\n ```\n\n **Example (multi-layer system):**\n ```bash\n # Layer 1: Workflow\n echo \"=== Secrets available in workflow: ===\"\n echo \"IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}\"\n\n # Layer 2: Build script\n echo \"=== Env vars in build script: ===\"\n env | grep IDENTITY || echo \"IDENTITY not in environment\"\n\n # Layer 3: Signing script\n echo \"=== Keychain state: ===\"\n security list-keychains\n security find-identity -v\n\n # Layer 4: Actual signing\n codesign --sign \"$IDENTITY\" --verbose=4 \"$APP\"\n ```\n\n **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)\n\n5. **Trace Data Flow**\n\n **WHEN error is deep in call stack:**\n\n See `root-cause-tracing.md` in this directory for the complete backward tracing technique.\n\n **Quick version:**\n - Where does bad value originate?\n - What called this with bad value?\n - Keep tracing up until you find the source\n - Fix at source, not at symptom\n\n### Phase 2: Pattern Analysis\n\n**Find the pattern before fixing:**\n\n1. **Find Working Examples**\n - Locate similar working code in same codebase\n - What works that's similar to what's broken?\n\n2. **Compare Against References**\n - If implementing pattern, read reference implementation COMPLETELY\n - Don't skim - read every line\n - Understand the pattern fully before applying\n\n3. **Identify Differences**\n - What's different between working and broken?\n - List every difference, however small\n - Don't assume \"that can't matter\"\n\n4. **Understand Dependencies**\n - What other components does this need?\n - What settings, config, environment?\n - What assumptions does it make?\n\n### Phase 3: Hypothesis and Testing\n\n**Scientific method:**\n\n1. **Form Single Hypothesis**\n - State clearly: \"I think X is the root cause because Y\"\n - Write it down\n - Be specific, not vague\n\n2. **Test Minimally**\n - Make the SMALLEST possible change to test hypothesis\n - One variable at a time\n - Don't fix multiple things at once\n\n3. **Verify Before Continuing**\n - Did it work? Yes → Phase 4\n - Didn't work? Form NEW hypothesis\n - DON'T add more fixes on top\n\n4. **When You Don't Know**\n - Say \"I don't understand X\"\n - Don't pretend to know\n - Ask for help\n - Research more\n\n### Phase 4: Implementation\n\n**Fix the root cause, not the symptom:**\n\n1. **Create Failing Test Case**\n - Simplest possible reproduction\n - Automated test if possible\n - One-off test script if no framework\n - MUST have before fixing\n - Use the `superpowers:test-driven-development` skill for writing proper failing tests\n\n2. **Implement Single Fix**\n - Address the root cause identified\n - ONE change at a time\n - No \"while I'm here\" improvements\n - No bundled refactoring\n\n3. **Verify Fix**\n - Test passes now?\n - No other tests broken?\n - Issue actually resolved?\n\n4. **If Fix Doesn't Work**\n - STOP\n - Count: How many fixes have you tried?\n - If < 3: Return to Phase 1, re-analyze with new information\n - **If ≥ 3: STOP and question the architecture (step 5 below)**\n - DON'T attempt Fix #4 without architectural discussion\n\n5. **If 3+ Fixes Failed: Question Architecture**\n\n **Pattern indicating architectural problem:**\n - Each fix reveals new shared state/coupling/problem in different place\n - Fixes require \"massive refactoring\" to implement\n - Each fix creates new symptoms elsewhere\n\n **STOP and question fundamentals:**\n - Is this pattern fundamentally sound?\n - Are we \"sticking with it through sheer inertia\"?\n - Should we refactor architecture vs. continue fixing symptoms?\n\n **Discuss with your human partner before attempting more fixes**\n\n This is NOT a failed hypothesis - this is a wrong architecture.\n\n## Red Flags - STOP and Follow Process\n\nIf you catch yourself thinking:\n- \"Quick fix for now, investigate later\"\n- \"Just try changing X and see if it works\"\n- \"Add multiple changes, run tests\"\n- \"Skip the test, I'll manually verify\"\n- \"It's probably X, let me fix that\"\n- \"I don't fully understand but this might work\"\n- \"Pattern says X but I'll adapt it differently\"\n- \"Here are the main problems: [lists fixes without investigation]\"\n- Proposing solutions before tracing data flow\n- **\"One more fix attempt\" (when already tried 2+)**\n- **Each fix reveals new problem in different place**\n\n**ALL of these mean: STOP. Return to Phase 1.**\n\n**If 3+ fixes failed:** Question the architecture (see Phase 4.5)\n\n## your human partner's Signals You're Doing It Wrong\n\n**Watch for these redirections:**\n- \"Is that not happening?\" - You assumed without verifying\n- \"Will it show us...?\" - You should have added evidence gathering\n- \"Stop guessing\" - You're proposing fixes without understanding\n- \"Ultrathink this\" - Question fundamentals, not just symptoms\n- \"We're stuck?\" (frustrated) - Your approach isn't working\n\n**When you see these:** STOP. Return to Phase 1.\n\n## Common Rationalizations\n\n| Excuse | Reality |\n|--------|---------|\n| \"Issue is simple, don't need process\" | Simple issues have root causes too. Process is fast for simple bugs. |\n| \"Emergency, no time for process\" | Systematic debugging is FASTER than guess-and-check thrashing. |\n| \"Just try this first, then investigate\" | First fix sets the pattern. Do it right from the start. |\n| \"I'll write test after confirming fix works\" | Untested fixes don't stick. Test first proves it. |\n| \"Multiple fixes at once saves time\" | Can't isolate what worked. Causes new bugs. |\n| \"Reference too long, I'll adapt the pattern\" | Partial understanding guarantees bugs. Read it completely. |\n| \"I see the problem, let me fix it\" | Seeing symptoms ≠ understanding root cause. |\n| \"One more fix attempt\" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |\n\n## Quick Reference\n\n| Phase | Key Activities | Success Criteria |\n|-------|---------------|------------------|\n| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |\n| **2. Pattern** | Find working examples, compare | Identify differences |\n| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |\n| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |\n\n## When Process Reveals \"No Root Cause\"\n\nIf systematic investigation reveals issue is truly environmental, timing-dependent, or external:\n\n1. You've completed the process\n2. Document what you investigated\n3. Implement appropriate handling (retry, timeout, error message)\n4. Add monitoring/logging for future investigation\n\n**But:** 95% of \"no root cause\" cases are incomplete investigation.\n\n## Supporting Techniques\n\nThese techniques are part of systematic debugging and available in this directory:\n\n- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger\n- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause\n- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling\n\n**Related skills:**\n- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)\n- **superpowers:verification-before-completion** - Verify fix worked before claiming success\n\n## Real-World Impact\n\nFrom debugging sessions:\n- Systematic approach: 15-30 minutes to fix\n- Random fixes approach: 2-3 hours of thrashing\n- First-time fix rate: 95% vs 40%\n- New bugs introduced: Near zero vs common\n"} |