claude-mpm 4.14.6__py3-none-any.whl → 4.21.0__py3-none-any.whl

claude_mpm/skills/bundled/debugging/systematic-debugging/references/troubleshooting.md

@@ -0,0 +1,449 @@
+# Debugging Troubleshooting Guide
+
+> **Part of**: [Systematic Debugging](../SKILL.md)
+> **Category**: debugging
+> **Reading Level**: Advanced
+
+## Purpose
+
+Solutions for common challenges that arise during systematic debugging, including what to do when you get stuck, when the process seems slow, or when human partners redirect you.
+
+## Common Debugging Challenges
+
+### Challenge 1: Cannot Reproduce Issue
+
+**Problem**: Bug reported but can't trigger it reliably
+
+**Solution Approach**:
+
+1. **Gather More Context**
+   ```
+   Ask reporter:
+   - Exact steps they took
+   - Browser/OS/environment details
+   - Screenshots or video
+   - Error messages they saw
+   - When it started happening
+   ```
+
+2. **Check for Environmental Factors**
+   - Time of day (server load patterns)
+   - User account state (permissions, data)
+   - Network conditions (latency, failures)
+   - Cache state (fresh vs cached)
+   - Concurrent operations
+
+3. **Add Comprehensive Logging**
+   ```typescript
+   // Log everything around suspected area
+   logger.info('Function entry', { input, state });
+   logger.info('Step 1 complete', { intermediate });
+   logger.info('Decision point', { condition, willTake: path });
+   logger.info('Function exit', { result });
+   ```
+
+4. **Monitor for Patterns**
+   - Does it happen at specific times?
+   - Only for certain users?
+   - Only on certain data?
+   - Percentage occurrence?
+
+**When to Stop**: If truly irreproducible after thorough investigation, document findings and add defensive error handling.
+
+### Challenge 2: Too Many Possible Causes
+
+**Problem**: Multiple things could cause this issue
+
+**Solution Approach**:
+
+1. **Binary Search**
+   ```
+   Disable half the functionality
+   → Still broken? Issue in remaining half
+   → Fixed? Issue in disabled half
+   Repeat until narrowed to single component
+   ```
+
+2. **Isolate Variables**
+   ```typescript
+   // Test each variable independently
+   const test1 = processWithA(data);
+   const test2 = processWithB(data);
+   const test3 = processWithC(data);
+
+   // Which fails?
+   ```
+
+3. **Priority by Likelihood**
+   ```
+   Most likely causes (based on evidence):
+   1. Recent code changes → Check first
+   2. Known fragile areas → Check second
+   3. External dependencies → Check third
+   4. Theoretical possibilities → Check last
+   ```
+
+4. **Eliminate Systematically**
+   - Start with most likely cause
+   - Test one hypothesis at a time
+   - Document which causes ruled out
+   - Don't test multiple theories simultaneously
+
+### Challenge 3: Error Messages Are Cryptic
+
+**Problem**: Error message doesn't clearly indicate root cause
+
+**Solution Approach**:
+
+1. **Search for Exact Error**
+   ```bash
+   # Google with quotes
+   "exact error message text"
+
+   # Search codebase
+   grep -r "exact error message" src/
+
+   # Check documentation
+   # Stack Overflow, GitHub issues
+   ```
+
+2. **Understand Error Source**
+   ```typescript
+   // Where is error thrown?
+   throw new Error('Cryptic message');
+
+   // Check call stack - WHO called this?
+   // Work backward from error
+   ```
+
+3. **Increase Verbosity**
+   ```bash
+   # Debug mode
+   DEBUG=* npm start
+
+   # Verbose flags
+   command --verbose --debug
+
+   # Enable all logging
+   LOG_LEVEL=debug
+   ```
+
+4. **Read Library Source**
+   - If error from library, read library code
+   - Check library issue tracker
+   - Look for related error messages
+
+### Challenge 4: Fix Doesn't Work
+
+**Problem**: Implemented fix but issue persists
+
+**Solution Approach**:
+
+1. **Verify Fix Actually Applied**
+   ```typescript
+   // Add logging to confirm
+   if (condition) {
+     console.log('FIX APPLIED: New code path');
+     // new code
+   }
+
+   // Did you see the log? If not, fix not reached.
+   ```
+
+2. **Check Fix Location**
+   - Fixed right file?
+   - Fixed right function?
+   - All instances fixed?
+   - Code recompiled/reloaded?
+
+3. **Verify Understanding**
+   - Was hypothesis correct?
+   - Did you misunderstand the problem?
+   - Is there a deeper issue?
+
+4. **Count Attempts**
+   - Attempt 1 failed → Re-analyze
+   - Attempt 2 failed → Deeper investigation
+   - **Attempt 3 failed → STOP, question architecture**
+
+### Challenge 5: Multiple Bugs Overlap
+
+**Problem**: Fixing one bug reveals another
+
+**Solution Approach**:
+
+1. **Separate Issues**
+   ```
+   Bug A: Authentication fails
+   Bug B: Authorization missing
+   Bug C: Error handling wrong
+
+   These are THREE separate bugs
+   Fix ONE at a time
+   ```
+
+2. **Priority Order**
+   - Fix deepest issue first (authentication)
+   - Then dependent issues (authorization)
+   - Then surface issues (error handling)
+
+3. **Track Each Separately**
+   ```
+   Create separate:
+   - Test cases
+   - Fixes
+   - Verifications
+
+   Don't bundle fixes
+   ```
+
+4. **If They Keep Cascading**
+   - This indicates architectural problem
+   - STOP fixing symptoms
+   - Discuss fundamental design with human partner
+
+### Challenge 6: Debugging Takes Too Long
+
+**Problem**: Hours spent, no progress
+
+**Solution Approach**:
+
+1. **Assess Current Phase**
+   ```
+   Still in Phase 1? → Not enough evidence gathered
+   Stuck in Phase 3? → Hypotheses too vague
+   Repeated Phase 4? → Wrong architecture
+   ```
+
+2. **Check for Red Flags**
+   - Making random changes? → Return to Phase 1
+   - Guessing without evidence? → Gather more data
+   - Fixing symptoms? → Find root cause
+   - 3+ fix attempts? → Question architecture
+
+3. **Start Over**
+   ```
+   If stuck after 2+ hours:
+   1. Write down everything you know
+   2. List assumptions you've made
+   3. Question each assumption
+   4. Start Phase 1 fresh
+   ```
+
+4. **Ask for Help**
+   - Explain to human partner
+   - Describe evidence gathered
+   - Share hypotheses tested
+   - Ask for guidance
+
+### Challenge 7: Human Partner Signals You're Wrong
+
+**Problem**: Human partner redirects you with questions
+
+**Common Signals**:
+
+| Signal | Meaning | Your Action |
+|--------|---------|-------------|
+| "Is that not happening?" | You assumed without verifying | Add evidence gathering |
+| "Will it show us...?" | You should have added diagnostics | Add logging/instrumentation |
+| "Stop guessing" | You're proposing fixes without understanding | Return to Phase 1 |
+| "Ultrathink this" | Question fundamentals, not symptoms | Question architecture |
+| "We're stuck?" (frustrated) | Your approach isn't working | Change debugging strategy |
+
+**Solution Approach**:
+
+1. **Recognize the Signal**
+   - Human partner is redirecting for a reason
+   - They see something you're missing
+   - Don't argue or defend
+
+2. **STOP Current Approach**
+   - Whatever you're doing isn't working
+   - Return to Phase 1
+   - Gather more evidence
+
+3. **Respond Appropriately**
+   ```
+   Signal: "Is that not happening?"
+   Response: "Let me verify that assumption with evidence"
+
+   Signal: "Stop guessing"
+   Response: "You're right, let me investigate the root cause first"
+
+   Signal: "We're stuck?"
+   Response: "Let me reconsider the approach from Phase 1"
+   ```
+
+4. **Learn the Pattern**
+   - Note what triggered the redirect
+   - Don't repeat that mistake
+   - Adjust debugging approach
+
+## When Systematic Approach Seems Slow
+
+### Perception vs Reality
+
+**Feeling**: "This process is taking too long, just try a quick fix"
+
+**Reality**:
+- Systematic: 15-45 minutes → correct fix
+- Random: 2-4 hours thrashing → maybe works
+
+**Remember**: Time spent in Phase 1 is time saved avoiding wrong fixes
+
+### Time Breakdown
+
+```
+Phase 1 (Root Cause):    10-20 minutes
+Phase 2 (Pattern):        5-10 minutes
+Phase 3 (Hypothesis):     5-10 minutes
+Phase 4 (Implementation): 5-15 minutes
+TOTAL:                   25-55 minutes
+
+Random Fix Approach:
+Attempt 1:               15 min → fails
+Attempt 2:               20 min → fails
+Attempt 3:               30 min → partially works
+Debug new issues:        60 min
+TOTAL:                   125+ minutes
+```
+
+### When It Actually IS Slow
+
+**If systematic approach taking 2+ hours:**
+
+1. **Check Evidence Quality**
+   - Logs detailed enough?
+   - Reproduction reliable?
+   - All layers instrumented?
+
+2. **Check Hypothesis Quality**
+   - Too vague?
+   - Not testable?
+   - Based on assumptions?
+
+3. **Check Fix Scope**
+   - Trying to fix too much at once?
+   - Bundling multiple issues?
+   - Over-engineering solution?
+
+## Process Shortcuts (When Appropriate)
+
+### Tiny Obvious Bugs
+
+**When**: Typo in variable name, missing comma, etc.
+
+**Shortcut**: Can fix immediately if:
+- [ ] You can see exact problem in error message
+- [ ] Fix is one-line change
+- [ ] Can verify fix in <30 seconds
+- [ ] Zero risk of side effects
+
+**Still Required**: Quick verification that fix works
+
+### Repeated Known Issues
+
+**When**: Same bug pattern seen before
+
+**Shortcut**: Can use known solution if:
+- [ ] 100% certain it's identical issue
+- [ ] Previous solution documented
+- [ ] Can verify match with evidence
+- [ ] Test case exists
+
+**Still Required**: Verify it actually matches
+
+### Development vs Production
+
+**Development**: Can be slightly less rigorous
+- Faster iteration acceptable
+- Can test fixes quickly
+- Easy rollback
+
+**Production**: ALWAYS full systematic process
+- High cost of being wrong
+- Limited testing ability
+- Difficult rollback
+
+## Recovery Strategies
+
+### If You Made Random Changes
+
+**Situation**: Violated systematic process, made changes without investigation
+
+**Recovery**:
+1. **Revert ALL changes** - back to known state
+2. **Document what you tried** - data for Phase 1
+3. **Start Phase 1 fresh** - use failed attempts as evidence
+4. **Don't keep "parts that might work"** - clean slate
+
+### If You're in Guess Loop
+
+**Situation**: Tried multiple fixes, none worked, now guessing
+
+**Recovery**:
+1. **Stop immediately** - more guesses won't help
+2. **Count attempts** - 3+? Architecture problem
+3. **Gather evidence** - instrument everything
+4. **Question fundamentals** - is approach wrong?
+
+### If Time Pressure Mounting
+
+**Situation**: Manager wants it fixed NOW, pressure to skip process
+
+**Recovery**:
+1. **Communicate reality** - "Systematic is faster than guessing"
+2. **Show progress** - "Phase 1 complete, identified root cause"
+3. **Set expectation** - "15 more minutes for correct fix"
+4. **Don't skip steps** - rushing guarantees rework
+
+## Tools for When Stuck
+
+### Rubber Duck Debugging
+
+Explain problem out loud (or in writing):
+1. What you're trying to debug
+2. What you've discovered
+3. What hypotheses you've tested
+4. What you're confused about
+
+Often reveals the issue.
+
+### Five Whys
+
+Keep asking "Why?" until you hit root cause:
+```
+Bug: Dashboard slow
+Why? → API calls taking long
+Why? → Database queries slow
+Why? → Missing indexes
+Why? → Recent migration didn't add them
+Why? → Migration script had bug
+```
+
+### Minimal Reproduction
+
+Strip everything until only broken part remains:
+- Remove unrelated code
+- Simplify inputs
+- Isolate single operation
+- Proves exact point of failure
+
+## Summary
+
+When debugging gets hard:
+- Cannot reproduce → Gather more context, add logging
+- Too many causes → Binary search, eliminate systematically
+- Cryptic errors → Search, increase verbosity, read source
+- Fix doesn't work → Verify applied, count attempts
+- Multiple bugs → Separate and prioritize
+- Taking too long → Assess phase, check for red flags
+- Human redirects → Recognize signal, return to Phase 1
+
+**Remember**: Systematic approach is FASTER than random fixes, especially when it seems slow.
+
+## Related References
+
+- [Workflow](workflow.md): Complete four-phase process
+- [Examples](examples.md): Real-world scenarios
+- [Anti-patterns](anti-patterns.md): What NOT to do