claude-mpm 5.4.55__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/skills/bundled/debugging/root-cause-tracing/references/tracing-techniques.md

@@ -0,0 +1,391 @@
+# Tracing Techniques
+
+Complete methodology for tracing bugs backward through call chains to find original triggers.
+
+## The Tracing Methodology
+
+### Overview
+
+Root cause tracing follows a systematic approach to walk backward through code execution until you find where bad data or invalid state originated.
+
+**Key insight:** The place where an error manifests is rarely where the bug actually lives.
+
+## Manual Tracing Process
+
+### Step 1: Observe the Symptom
+
+**What to capture:**
+- Exact error message
+- Stack trace (if available)
+- Failed operation
+- Wrong value/state
+- Location where error occurred
+
+**Example:**
+```
+Error: git init failed in /Users/jesse/project/packages/core
+  at WorktreeManager.createSessionWorktree (worktree-manager.ts:45)
+```
+
+**Questions to ask:**
+- What operation failed?
+- What was the expected behavior?
+- What value/state is wrong?
+- Where did the error manifest?
+
+### Step 2: Find Immediate Cause
+
+Look at the code where the error occurs.
+
+**Example:**
+```typescript
+async function createSessionWorktree(projectDir: string, sessionId: string) {
+  // This is where it fails
+  await execFileAsync('git', ['init'], { cwd: projectDir });
+}
+```
+
+**Questions to ask:**
+- What code directly causes this error?
+- What parameters does it receive?
+- What assumptions does it make?
+- Are the parameters valid?
+
+### Step 3: Identify the Caller
+
+Trace one level up the call stack.
+
+**From stack trace:**
+```
+  at WorktreeManager.createSessionWorktree (worktree-manager.ts:45)
+  at Session.initializeWorkspace (session.ts:78)
+  at Session.create (session.ts:34)
+  at Test.<anonymous> (project.test.ts:12)
+```
+
+**Manual code inspection:**
+```typescript
+// In session.ts
+static async create(name: string, projectDir: string) {
+  const session = new Session(name);
+  await session.initializeWorkspace(projectDir); // ← Caller
+  return session;
+}
+```
+
+**Questions to ask:**
+- What function called this?
+- What value did it pass?
+- Where did that value come from?
+
+### Step 4: Continue Tracing Up
+
+Repeat step 3 for each caller until you find the source.
+
+**Trace chain example:**
+```
+Test code (project.test.ts:12)
+  → Project.create(name, context.tempDir)
+    → Session.create(name, projectDir)
+      → Session.initializeWorkspace(projectDir)
+        → WorktreeManager.createSessionWorktree(projectDir, sessionId)
+          → execFileAsync('git', ['init'], { cwd: projectDir })
+            → ERROR: projectDir is empty string
+```
+
+**Working backward:**
+- Where did `projectDir = ''` come from? → Session.create()
+- Where did Session.create() get it? → Project.create()
+- Where did Project.create() get it? → Test code
+- Where did test code get it? → `context.tempDir`
+- Where did `context.tempDir = ''` come from? → **ROOT CAUSE FOUND**
+
+### Step 5: Identify Root Cause
+
+The root cause is where bad data/state originates.
+
+**Common root causes:**
+- Uninitialized variables accessed too early
+- Configuration not loaded
+- Null/undefined not handled
+- Wrong default value
+- Timing issue (race condition)
+- Environment-specific behavior
+
+**In our example:**
+```typescript
+// Root cause: Getter returns empty string before initialization
+function setupCoreTest() {
+  let _tempDir = ''; // ← BAD: Empty string default
+
+  beforeEach(() => {
+    _tempDir = createTempDir(); // ← Set later
+  });
+
+  return { tempDir: _tempDir }; // ← Returns '' initially!
+}
+
+// Test code runs at module load time
+const context = setupCoreTest();
+const PROJECT_DIR = context.tempDir; // ← '' before beforeEach runs!
+```
+
+## Tracing Patterns
+
+### Pattern 1: Data Flow Tracing
+
+**When to use:** Invalid data appears somewhere in execution
+
+**Process:**
+1. Identify the invalid data at error point
+2. Trace backward to find where it was set
+3. Continue to where it originated
+4. Fix at origin
+
+**Example:**
+```
+userId = 0 (invalid) at database query
+  ← from request.userId
+    ← from parseRequest(req)
+      ← from req.headers['user-id']
+        ← ROOT: Header not validated/defaulted
+```
+
+### Pattern 2: Call Chain Tracing
+
+**When to use:** Error happens deep in call stack
+
+**Process:**
+1. Start at error location
+2. Examine immediate caller
+3. Move up one level
+4. Repeat until finding where invalid call originates
+
+**Example:**
+```
+Error in database.execute(query)
+  ← from UserService.findUser(id)
+    ← from AuthMiddleware.authenticate()
+      ← from Router.handleRequest()
+        ← ROOT: No authentication check before calling
+```
+
+### Pattern 3: State Mutation Tracing
+
+**When to use:** Object/variable has wrong value at some point
+
+**Process:**
+1. Identify when state is wrong
+2. Find all places that mutate state
+3. Trace backward to find which mutation caused it
+4. Find why that mutation happened
+
+**Example:**
+```
+config.database = undefined at startup
+  ← config.database set to undefined in validateConfig()
+    ← because env.DATABASE_URL is undefined
+      ← ROOT: Environment variable not set
+```
+
+### Pattern 4: Timing/Ordering Tracing
+
+**When to use:** Issue involves race conditions or execution order
+
+**Process:**
+1. Identify operations that ran in wrong order
+2. Trace why the order is wrong
+3. Find what controls the ordering
+4. Fix ordering logic
+
+**Example:**
+```
+Database query before connection established
+  ← query() called in constructor
+    ← constructor runs immediately
+      ← connection.connect() called async in initialize()
+        ← ROOT: Constructor doesn't wait for async initialization
+```
+
+## Decision Trees
+
+### When Manual Tracing is Sufficient
+
+```
+Can you see the code path?
+  → Yes: Use manual tracing
+    → Stack trace available?
+      → Yes: Follow stack trace
+      → No: Inspect caller manually
+  → No: Add instrumentation (see advanced-techniques.md)
+
+Is error reproducible?
+  → Yes: Can trace reliably
+  → No: Must make reproducible first
+    → Add logging to capture when it happens
+    → Use instrumentation to understand timing
+```
+
+### How Deep to Trace
+
+```
+Found where bad value originates?
+  → Yes: Root cause found
+  → No: Continue tracing
+    → At system boundary (entry point)?
+      → Yes: Root cause is at boundary
+      → No: Keep tracing backward
+
+Multiple callers with same issue?
+  → Yes: Root cause is in shared caller
+  → No: Root cause is in specific caller path
+```
+
+### Fixing vs Adding Defense
+
+```
+Found root cause?
+  → Yes:
+    → Fix at source: YES
+    → Add validation at intermediate layers: YES
+    → Fix only at error point: NO
+  → No:
+    → Add defense at error point: TEMPORARY
+    → Continue tracing: YES
+```
+
+## Common Tracing Challenges
+
+### Challenge 1: Long Call Chains
+
+**Problem:** 10+ levels in call stack
+**Solution:**
+- Use binary search: check middle of chain first
+- Skip obviously correct intermediate calls
+- Focus on where data changes
+
+### Challenge 2: Async/Callback Hell
+
+**Problem:** Callbacks and promises obscure call chain
+**Solution:**
+- Use async stack traces (Node.js: `--async-stack-traces`)
+- Add trace IDs to log all operations
+- Use debugger to step through promises
+
+### Challenge 3: Multiple Code Paths
+
+**Problem:** Error could come from multiple callers
+**Solution:**
+- Add conditional logging at error point
+- Use instrumentation to capture caller info
+- Reproduce with minimal test case
+
+### Challenge 4: External Dependencies
+
+**Problem:** Issue might be in third-party library
+**Solution:**
+- Verify inputs to library are correct
+- Check library version/compatibility
+- Read library source if needed
+- Consider if misusing library API
+
+### Challenge 5: No Stack Trace
+
+**Problem:** Error doesn't produce stack trace
+**Solution:**
+- Add stack capture: `new Error().stack`
+- Use debugger to pause at error point
+- Add logging at suspected callers
+- Use process of elimination
+
+## Tips for Effective Tracing
+
+### Use Your Tools
+
+**IDE navigation:**
+- "Find References" to see all callers
+- "Go to Definition" to jump to implementation
+- Call hierarchy view
+- Type hierarchy for inheritance
+
+**Debugger:**
+- Set breakpoint at error point
+- Step out to see caller
+- Examine call stack panel
+- Watch variables as they change
+
+**Version control:**
+- `git blame` to see when code changed
+- `git log` to see recent changes
+- `git bisect` to find when bug was introduced
+
+### Document Your Trace
+
+As you trace, write down the call chain:
+
+```
+ERROR: git init in wrong directory
+  ← execFileAsync('git', ['init'], { cwd: '' })
+  ← WorktreeManager.createSessionWorktree(projectDir='')
+  ← Session.initializeWorkspace(projectDir='')
+  ← Session.create(name, projectDir='')
+  ← Project.create(name, context.tempDir='')
+  ← Test: const PROJECT_DIR = context.tempDir
+  ← ROOT: setupCoreTest() returns { tempDir: '' } before beforeEach
+```
+
+This helps you:
+- Remember where you are in the trace
+- Communicate findings to others
+- Verify your understanding
+- Identify patterns
+
+### Know When to Stop Tracing
+
+**Stop when you find:**
+- The origin of bad data
+- The first place where invariant is violated
+- The entry point where validation should happen
+- The configuration/initialization that sets wrong value
+
+**Don't stop at:**
+- Where error manifests
+- Where symptom is visible
+- Intermediate validation that fails
+- Defensive checks that catch the issue
+
+## Verification After Tracing
+
+Once you think you've found the root cause:
+
+1. **Verify understanding:**
+   - Can you explain how the bug happens?
+   - Does your explanation match all symptoms?
+   - Can you predict what will happen if you fix it?
+
+2. **Test your hypothesis:**
+   - Add temporary fix at suspected root cause
+   - Does it resolve the issue?
+   - Does it resolve ALL instances of the issue?
+
+3. **Implement proper fix:**
+   - Fix at root cause
+   - Add tests for root cause
+   - Add defense-in-depth at intermediate layers
+   - Verify no regressions
+
+## Summary
+
+**Manual tracing process:**
+1. Observe symptom → 2. Find immediate cause → 3. Identify caller → 4. Trace up → 5. Find root cause
+
+**Key principles:**
+- Trace backward from symptom to source
+- Don't stop at first "cause" - find original trigger
+- Fix at source, add defense at layers
+- Document your trace for clarity
+
+**When to use advanced techniques:**
+- Can't manually trace (see advanced-techniques.md)
+- Need to identify which test pollutes (see advanced-techniques.md)
+- Multiple async operations involved (see advanced-techniques.md)

claude_mpm/skills/bundled/debugging/systematic-debugging/CREATION-LOG.md

@@ -0,0 +1,119 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+*Created: 2025-10-03*
+*Purpose: Reference example for skill extraction and bulletproofing*

claude_mpm/skills/bundled/debugging/systematic-debugging/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: systematic-debugging
+description: Methodical debugging instead of random changes
+version: 2.2.0
+category: debugging
+author: Jesse Vincent
+license: MIT
+source: https://github.com/obra/superpowers-skills/tree/main/skills/debugging/systematic-debugging
+progressive_disclosure:
+  entry_point:
+    summary: "Replace random code changes with systematic problem diagnosis using four-phase investigation framework"
+    when_to_use: "When user reports bugs, errors, test failures, or unexpected behavior. ESPECIALLY when under time pressure or 'quick fixes' seem obvious."
+    quick_start: "1. Read error messages completely 2. Reproduce consistently 3. Form specific hypothesis 4. Test with single change 5. Verify fix"
+  references:
+    - workflow.md
+    - examples.md
+    - troubleshooting.md
+    - anti-patterns.md
+context_limit: 800
+tags:
+  - debugging
+  - problem-solving
+  - root-cause
+  - systematic
+requires_tools:
+  - debugger
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+This skill enforces a four-phase systematic approach that ensures root cause investigation before any fix attempt. Violating the letter of this process is violating the spirit of debugging.
+
+## When to Use This Skill
+
+Activate when:
+- User reports a bug or error
+- Test failures occur
+- Code behaves unexpectedly
+- Performance problems arise
+- Build or integration failures
+- User says "it's not working"
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## Core Principles
+
+1. **Reproduce First**: Ensure you can reliably reproduce the issue
+2. **One Change at a Time**: Change only one thing between tests
+3. **Hypothesis-Driven**: Form hypotheses before making changes
+4. **Verify Fixes**: Confirm the fix works and doesn't break anything else
+
+## Quick Start
+
+1. **Read Error Messages**: Read completely, including stack traces
+2. **Reproduce Consistently**: Create reliable reproduction steps
+3. **Gather Evidence**: Add diagnostic instrumentation in multi-component systems
+4. **Form Hypothesis**: State clearly "I think X because Y"
+5. **Test Minimally**: Make smallest possible change
+6. **Verify Fix**: Confirm resolution and no regressions
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+- Read error messages carefully (they often contain the solution)
+- Reproduce consistently
+- Check recent changes
+- Gather evidence in multi-component systems
+- Trace data flow back to source
+
+### Phase 2: Pattern Analysis
+
+Find working examples, compare against references, identify differences, understand dependencies.
+
+### Phase 3: Hypothesis and Testing
+
+Form single hypothesis, test minimally (one variable at a time), verify before continuing.
+
+### Phase 4: Implementation
+
+Create failing test case, implement single fix addressing root cause, verify fix works.
+
+**If 3+ fixes fail:** STOP and question the architecture - this indicates architectural problems, not failed hypotheses.
+
+## Navigation
+
+For detailed information:
+- **[Workflow](references/workflow.md)**: Complete four-phase debugging workflow with decision trees and detailed steps
+- **[Examples](references/examples.md)**: Real-world debugging scenarios with step-by-step walkthroughs
+- **[Troubleshooting](references/troubleshooting.md)**: Common debugging challenges and how to overcome them
+- **[Anti-patterns](references/anti-patterns.md)**: Common mistakes, rationalizations, and red flags
+
+## Key Reminders
+
+- NEVER make random changes hoping they'll work
+- ALWAYS reproduce the issue before attempting fixes
+- Form hypothesis BEFORE making changes
+- Change ONE thing at a time
+- Verify fix actually resolves the issue
+- Check for regressions after fixing
+- If 3+ fixes fail, question the architecture
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Integration with Other Skills
+
+- **root-cause-tracing**: How to trace back through call stack
+- **defense-in-depth**: Add validation after finding root cause
+- **condition-based-waiting**: Replace timeouts identified in Phase 2
+- **verification-before-completion**: Verify fix worked before claiming success
+- **test-driven-development**: Create failing test case in Phase 4
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common