claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/skills/bundled/collaboration/writing-plans/references/plan-structure-templates.md

@@ -0,0 +1,312 @@
+# Plan Structure Templates
+
+## Standard Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** Use `${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/executing-plans/SKILL.md` to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Template Structure
+
+```markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+```
+
+## Bite-Sized Task Examples
+
+### Example 1: Database Model
+
+```markdown
+### Task 1: User Model and Schema
+
+**Files:**
+- Create: `src/models/user.py`
+- Create: `tests/models/test_user.py`
+- Create: `migrations/001_create_users_table.sql`
+
+**Step 1: Write the failing test**
+
+```python
+def test_user_model_creation():
+    user = User(username="alice", email="alice@example.com")
+    assert user.username == "alice"
+    assert user.email == "alice@example.com"
+    assert user.created_at is not None
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/models/test_user.py::test_user_model_creation -v`
+Expected: FAIL with "ModuleNotFoundError: No module named 'models.user'"
+
+**Step 3: Write minimal implementation**
+
+In `src/models/user.py`:
+```python
+from datetime import datetime
+from dataclasses import dataclass
+
+@dataclass
+class User:
+    username: str
+    email: str
+    created_at: datetime = None
+
+    def __post_init__(self):
+        if self.created_at is None:
+            self.created_at = datetime.utcnow()
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/models/test_user.py::test_user_model_creation -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/models/user.py tests/models/test_user.py
+git commit -m "feat: add User model with basic fields"
+```
+```
+
+### Example 2: API Endpoint
+
+```markdown
+### Task 3: GET /users/:id Endpoint
+
+**Files:**
+- Modify: `src/api/routes.py:15` (add route)
+- Create: `src/api/handlers/users.py`
+- Create: `tests/api/test_users_endpoint.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_get_user_by_id(client, db_with_users):
+    response = client.get("/users/1")
+    assert response.status_code == 200
+    assert response.json["username"] == "alice"
+    assert response.json["email"] == "alice@example.com"
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/api/test_users_endpoint.py::test_get_user_by_id -v`
+Expected: FAIL with "404 Not Found"
+
+**Step 3: Write minimal implementation**
+
+In `src/api/handlers/users.py`:
+```python
+from flask import jsonify
+from src.models.user import User
+from src.db import get_db
+
+def get_user(user_id):
+    db = get_db()
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+    return jsonify({
+        "id": user.id,
+        "username": user.username,
+        "email": user.email
+    })
+```
+
+In `src/api/routes.py` at line 15:
+```python
+from src.api.handlers.users import get_user
+
+# Add this route
+app.route("/users/<int:user_id>", methods=["GET"])(get_user)
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/api/test_users_endpoint.py::test_get_user_by_id -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/api/handlers/users.py src/api/routes.py tests/api/test_users_endpoint.py
+git commit -m "feat: add GET /users/:id endpoint"
+```
+```
+
+## Granularity Guidelines
+
+**Each step should take 2-5 minutes:**
+
+✅ **Good granularity:**
+- "Write the failing test" - single test function
+- "Run it to make sure it fails" - one command
+- "Implement the minimal code to make the test pass" - focused function
+- "Run the tests and make sure they pass" - verify
+- "Commit" - checkpoint
+
+❌ **Too large (split these up):**
+- "Implement the user authentication system" - needs 10+ tasks
+- "Add validation and error handling" - multiple tests/steps
+- "Create all the models" - one task per model
+
+❌ **Too small (combine these):**
+- "Import the datetime module" - part of implementation step
+- "Type the function signature" - part of implementation step
+- "Add one line of code" - too granular
+
+## Multi-File Task Structure
+
+When a task involves multiple related files:
+
+```markdown
+### Task 4: Email Validation with Helper
+
+**Files:**
+- Create: `src/utils/validators.py`
+- Create: `tests/utils/test_validators.py`
+- Modify: `src/models/user.py:12` (use validator)
+- Modify: `tests/models/test_user.py` (add validation tests)
+
+**Step 1: Write failing test for validator**
+
+In `tests/utils/test_validators.py`:
+```python
+def test_validate_email_valid():
+    assert validate_email("alice@example.com") == True
+
+def test_validate_email_invalid():
+    assert validate_email("not-an-email") == False
+```
+
+**Step 2: Run validator test to verify it fails**
+
+Run: `pytest tests/utils/test_validators.py -v`
+Expected: FAIL with "NameError: name 'validate_email' is not defined"
+
+**Step 3: Implement email validator**
+
+In `src/utils/validators.py`:
+```python
+import re
+
+def validate_email(email: str) -> bool:
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return bool(re.match(pattern, email))
+```
+
+**Step 4: Run validator test to verify it passes**
+
+Run: `pytest tests/utils/test_validators.py -v`
+Expected: PASS (both tests)
+
+**Step 5: Write failing test for User model validation**
+
+In `tests/models/test_user.py`:
+```python
+def test_user_model_rejects_invalid_email():
+    with pytest.raises(ValueError, match="Invalid email"):
+        User(username="alice", email="not-an-email")
+```
+
+**Step 6: Run User model test to verify it fails**
+
+Run: `pytest tests/models/test_user.py::test_user_model_rejects_invalid_email -v`
+Expected: FAIL (no validation yet)
+
+**Step 7: Add validation to User model**
+
+In `src/models/user.py` at line 12:
+```python
+from src.utils.validators import validate_email
+
+@dataclass
+class User:
+    username: str
+    email: str
+    created_at: datetime = None
+
+    def __post_init__(self):
+        if not validate_email(self.email):
+            raise ValueError(f"Invalid email: {self.email}")
+        if self.created_at is None:
+            self.created_at = datetime.utcnow()
+```
+
+**Step 8: Run User model test to verify it passes**
+
+Run: `pytest tests/models/test_user.py::test_user_model_rejects_invalid_email -v`
+Expected: PASS
+
+**Step 9: Run all tests to ensure nothing broke**
+
+Run: `pytest tests/ -v`
+Expected: All tests PASS
+
+**Step 10: Commit**
+
+```bash
+git add src/utils/validators.py tests/utils/test_validators.py src/models/user.py tests/models/test_user.py
+git commit -m "feat: add email validation to User model"
+```
+```
+
+## Plan File Naming Convention
+
+Save plans to: `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+**Examples:**
+- `docs/plans/2025-01-15-user-authentication.md`
+- `docs/plans/2025-01-16-api-rate-limiting.md`
+- `docs/plans/2025-01-17-database-migration-users.md`

claude_mpm/skills/bundled/debugging/root-cause-tracing/SKILL.md

@@ -2,8 +2,24 @@
 name: Root Cause Tracing
 description: Systematically trace bugs backward through call stack to find original trigger
 when_to_use: when errors occur deep in execution and you need to trace back to find the original trigger
-version: 1.1.0
+version: 2.0.0
 languages: all
+progressive_disclosure:
+  entry_point:
+    summary: "Trace bugs backward through call chains to find original triggers instead of fixing symptoms"
+    when_to_use: "When errors manifest deep in execution, unclear data origins, or long call chains. Use AFTER systematic-debugging Phase 1."
+    quick_start: "1. Observe symptom 2. Find immediate cause 3. Ask what called this 4. Keep tracing up 5. Fix at source + add defense"
+  references:
+    - tracing-techniques.md
+    - examples.md
+    - advanced-techniques.md
+    - integration.md
+context_limit: 800
+tags:
+  - debugging
+  - root-cause
+  - tracing
+  - call-stack
 ---
 
 # Root Cause Tracing
@@ -14,159 +30,115 @@ Bugs often manifest deep in the call stack (git init in wrong directory, file cr
 
 **Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
 
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Bug appears deep in stack?" [shape=diamond];
-    "Can trace backwards?" [shape=diamond];
-    "Fix at symptom point" [shape=box];
-    "Trace to original trigger" [shape=box];
-    "BETTER: Also add defense-in-depth" [shape=box];
-
-    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
-    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
-    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
-    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
-}
-```
+This skill is a specialized technique within the systematic-debugging workflow, typically applied during Phase 1 (Root Cause Investigation) when dealing with deep call stacks.
+
+## When to Use This Skill
 
-**Use when:**
+**Use root-cause-tracing when:**
 - Error happens deep in execution (not at entry point)
 - Stack trace shows long call chain
 - Unclear where invalid data originated
 - Need to find which test/code triggers the problem
+- Symptom appears far from actual cause
 
-## The Tracing Process
+**Relationship with systematic-debugging:**
+- systematic-debugging: The overall framework (Phases 1-4)
+- root-cause-tracing: A specific technique for Phase 1 investigation
+- Use root-cause-tracing WITHIN systematic-debugging Phase 1
+
+## The Iron Law
 
-### 1. Observe the Symptom
 ```
-Error: git init failed in /Users/jesse/project/packages/core
+NEVER FIX JUST WHERE THE ERROR APPEARS
+ALWAYS TRACE BACK TO FIND THE ORIGINAL TRIGGER
 ```
 
-### 2. Find Immediate Cause
-**What code directly causes this?**
-```typescript
-await execFileAsync('git', ['init'], { cwd: projectDir });
-```
+Fixing symptoms creates bandaid solutions that mask root problems.
 
-### 3. Ask: What Called This?
-```typescript
-WorktreeManager.createSessionWorktree(projectDir, sessionId)
-  → called by Session.initializeWorkspace()
-  → called by Session.create()
-  → called by test at Project.create()
-```
+## Core Principles
 
-### 4. Keep Tracing Up
-**What value was passed?**
-- `projectDir = ''` (empty string!)
-- Empty string as `cwd` resolves to `process.cwd()`
-- That's the source code directory!
-
-### 5. Find Original Trigger
-**Where did empty string come from?**
-```typescript
-const context = setupCoreTest(); // Returns { tempDir: '' }
-Project.create('name', context.tempDir); // Accessed before beforeEach!
-```
+1. **Trace Backward**: Follow call chain from symptom to source
+2. **Find Original Trigger**: Identify where bad data/state originated
+3. **Fix at Source**: Address root cause, not symptom
+4. **Defense-in-Depth**: Add validation at each layer after fixing source
+
+## Quick Start
 
-## Adding Stack Traces
+### The 5-Step Trace Process
 
-When you can't trace manually, add instrumentation:
+1. **Observe the Symptom**: What error message? What failed operation?
+2. **Find Immediate Cause**: What code directly causes this error?
+3. **Ask What Called This**: Trace one level up the call stack
+4. **Keep Tracing Up**: Continue until you find the original trigger
+5. **Fix at Source + Defense**: Fix root cause and add layer validation
 
-```typescript
-// Before the problematic operation
-async function gitInit(directory: string) {
-  const stack = new Error().stack;
-  console.error('DEBUG git init:', {
-    directory,
-    cwd: process.cwd(),
-    nodeEnv: process.env.NODE_ENV,
-    stack,
-  });
+### Decision Tree
 
-  await execFileAsync('git', ['init'], { cwd: directory });
-}
+```
+Error appears deep in stack?
+  → Yes: Start tracing backward
+    → Can identify caller? → Trace one level up → Repeat
+    → Cannot identify caller? → Add instrumentation (see advanced-techniques.md)
+  → No: May not need tracing (error at entry point)
 ```
 
-**Critical:** Use `console.error()` in tests (not logger - may not show)
+## The Tracing Process
 
-**Run and capture:**
-```bash
-npm test 2>&1 | grep 'DEBUG git init'
+**Example: Git init in wrong directory**
+```
+Error symptom → execFileAsync('git', ['init'], { cwd: '' })
+  ← WorktreeManager.createSessionWorktree(projectDir='')
+  ← Session.create() → Project.create() → Test code
+  ← ROOT CAUSE: setupCoreTest() returns { tempDir: '' } before beforeEach
 ```
 
-**Analyze stack traces:**
-- Look for test file names
-- Find the line number triggering the call
-- Identify the pattern (same test? same parameter?)
+**At each level ask:** Where did this value come from? Is this the origin?
 
-## Finding Which Test Causes Pollution
+**For detailed tracing methodology, see [Tracing Techniques](references/tracing-techniques.md)**
+**For complete real-world examples, see [Examples](references/examples.md)**
 
-If something appears during tests but you don't know which test:
+## After Finding Root Cause
 
-Use the bisection script: @find-polluter.sh
+**Fix at source** (throw if accessed before initialization) + **Add defense-in-depth** (validate at Project.create, WorkspaceManager, environment guards, instrumentation).
 
-```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts'
-```
+This prevents similar bugs and catches issues earlier.
 
-Runs tests one-by-one, stops at first polluter. See script for usage.
-
-## Real Example: Empty projectDir
-
-**Symptom:** `.git` created in `packages/core/` (source code)
-
-**Trace chain:**
-1. `git init` runs in `process.cwd()` ← empty cwd parameter
-2. WorktreeManager called with empty projectDir
-3. Session.create() passed empty string
-4. Test accessed `context.tempDir` before beforeEach
-5. setupCoreTest() returns `{ tempDir: '' }` initially
-
-**Root cause:** Top-level variable initialization accessing empty value
-
-**Fix:** Made tempDir a getter that throws if accessed before beforeEach
-
-**Also added defense-in-depth:**
-- Layer 1: Project.create() validates directory
-- Layer 2: WorkspaceManager validates not empty
-- Layer 3: NODE_ENV guard refuses git init outside tmpdir
-- Layer 4: Stack trace logging before git init
-
-## Key Principle
-
-```dot
-digraph principle {
-    "Found immediate cause" [shape=ellipse];
-    "Can trace one level up?" [shape=diamond];
-    "Trace backwards" [shape=box];
-    "Is this the source?" [shape=diamond];
-    "Fix at source" [shape=box];
-    "Add validation at each layer" [shape=box];
-    "Bug impossible" [shape=doublecircle];
-    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
-
-    "Found immediate cause" -> "Can trace one level up?";
-    "Can trace one level up?" -> "Trace backwards" [label="yes"];
-    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
-    "Trace backwards" -> "Is this the source?";
-    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
-    "Is this the source?" -> "Fix at source" [label="yes"];
-    "Fix at source" -> "Add validation at each layer";
-    "Add validation at each layer" -> "Bug impossible";
-}
-```
+## Navigation
+
+For detailed information:
+- **[Tracing Techniques](references/tracing-techniques.md)**: Complete tracing methodology, patterns, and decision trees
+- **[Examples](references/examples.md)**: Real-world debugging scenarios with full trace chains
+- **[Advanced Techniques](references/advanced-techniques.md)**: Stack traces, instrumentation, test pollution detection
+- **[Integration](references/integration.md)**: How to use with systematic-debugging and other skills
+
+## Key Reminders
 
-**NEVER fix just where the error appears.** Trace back to find the original trigger.
+- NEVER fix just where the error appears
+- ALWAYS trace back to find the original trigger
+- Use `console.error()` for debugging in tests (logger may be suppressed)
+- Log BEFORE the dangerous operation, not after it fails
+- Include context: directory, cwd, environment, timestamps
+- Add defense-in-depth after fixing source
+- Document your trace as you go (write down the call chain)
 
-## Stack Trace Tips
+## Red Flags - STOP
 
-**In tests:** Use `console.error()` not logger - logger may be suppressed
-**Before operation:** Log before the dangerous operation, not after it fails
-**Include context:** Directory, cwd, environment variables, timestamps
-**Capture stack:** `new Error().stack` shows complete call chain
+If you catch yourself thinking:
+- "I'll just add validation here" (without finding source)
+- "This will prevent the error" (symptom fix)
+- "Too hard to trace back" (add instrumentation instead)
+- "Quick fix for now" (creates technical debt)
+
+**ALL of these mean: Continue tracing to find root cause.**
+
+## Integration with Other Skills
+
+- **systematic-debugging**: Use root-cause-tracing during Phase 1
+- **defense-in-depth**: Add after finding root cause
+- **verification-before-completion**: Verify fix worked at source
+- **test-driven-development**: Write test for root cause, not symptom
+
+See [Integration](references/integration.md) for complete workflow examples.
 
 ## Real-World Impact
 
@@ -175,3 +147,6 @@ From debugging session (2025-10-03):
 - Fixed at source (getter validation)
 - Added 4 layers of defense
 - 1847 tests passed, zero pollution
+- Time saved: 3+ hours vs symptom-fix approach
+
+**Bottom line:** Tracing takes 15-30 minutes. Symptom fixes take hours of whack-a-mole.

claude_mpm/skills/bundled/debugging/root-cause-tracing/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0