claude-mpm 4.1.26__py3-none-any.whl → 4.24.0__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/database-migration.md

@@ -0,0 +1,199 @@
+---
+skill_id: database-migration
+skill_version: 0.1.0
+description: Safe patterns for evolving database schemas in production.
+updated_at: 2025-10-30T17:00:00Z
+tags: [database, migration, schema, production]
+---
+
+# Database Migration
+
+Safe patterns for evolving database schemas in production.
+
+## Migration Principles
+
+1. **Backward compatible** - New code works with old schema
+2. **Reversible** - Can rollback if needed
+3. **Tested** - Verify on staging before production
+4. **Incremental** - Small changes, not big-bang
+5. **Zero downtime** - No service interruption
+
+## Safe Migration Pattern
+
+### Phase 1: Add New (Compatible)
+```sql
+-- Add new column (nullable initially)
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255) NULL;
+
+-- Deploy new code that writes to both old and new
+UPDATE users SET full_name = CONCAT(first_name, ' ', last_name);
+```
+
+### Phase 2: Migrate Data
+```sql
+-- Backfill existing data
+UPDATE users
+SET full_name = CONCAT(first_name, ' ', last_name)
+WHERE full_name IS NULL;
+```
+
+### Phase 3: Make Required
+```sql
+-- Make column required
+ALTER TABLE users ALTER COLUMN full_name SET NOT NULL;
+```
+
+### Phase 4: Remove Old (After New Code Deployed)
+```sql
+-- Remove old columns
+ALTER TABLE users DROP COLUMN first_name;
+ALTER TABLE users DROP COLUMN last_name;
+```
+
+## Common Migrations
+
+### Adding Index
+```sql
+-- Create index concurrently (PostgreSQL)
+CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
+```
+
+### Renaming Column
+```sql
+-- Phase 1: Add new column
+ALTER TABLE users ADD COLUMN email_address VARCHAR(255);
+
+-- Phase 2: Copy data
+UPDATE users SET email_address = email;
+
+-- Phase 3: Drop old column (after deploy)
+ALTER TABLE users DROP COLUMN email;
+```
+
+### Changing Column Type
+```sql
+-- Phase 1: Add new column with new type
+ALTER TABLE products ADD COLUMN price_cents INTEGER;
+
+-- Phase 2: Migrate data
+UPDATE products SET price_cents = CAST(price * 100 AS INTEGER);
+
+-- Phase 3: Drop old column
+ALTER TABLE products DROP COLUMN price;
+ALTER TABLE products RENAME COLUMN price_cents TO price;
+```
+
+### Adding Foreign Key
+```sql
+-- Add column first
+ALTER TABLE orders ADD COLUMN user_id INTEGER NULL;
+
+-- Populate data
+UPDATE orders SET user_id = (
+    SELECT id FROM users WHERE users.email = orders.user_email
+);
+
+-- Add foreign key
+ALTER TABLE orders
+ADD CONSTRAINT fk_orders_users
+FOREIGN KEY (user_id) REFERENCES users(id);
+```
+
+## Migration Tools
+
+### Python (Alembic)
+```python
+# Generate migration
+alembic revision --autogenerate -m "add user full_name"
+
+# Apply migration
+alembic upgrade head
+
+# Rollback
+alembic downgrade -1
+```
+
+### JavaScript (Knex)
+```javascript
+// Create migration
+knex migrate:make add_full_name
+
+// Apply migrations
+knex migrate:latest
+
+// Rollback
+knex migrate:rollback
+```
+
+### Rails
+```ruby
+# Generate migration
+rails generate migration AddFullNameToUsers full_name:string
+
+# Run migrations
+rails db:migrate
+
+# Rollback
+rails db:rollback
+```
+
+## Testing Migrations
+
+```python
+def test_migration_forward_backward():
+    # Apply migration
+    apply_migration("add_full_name")
+
+    # Verify schema
+    assert column_exists("users", "full_name")
+
+    # Rollback
+    rollback_migration()
+
+    # Verify rollback
+    assert not column_exists("users", "full_name")
+```
+
+## Dangerous Operations
+
+### ❌ Avoid in Production
+```sql
+-- Locks table for long time
+ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;
+
+-- Can't rollback
+DROP TABLE old_users;
+
+-- Breaks existing code immediately
+ALTER TABLE users DROP COLUMN email;
+```
+
+### ✅ Safe Alternatives
+```sql
+-- Add as nullable first
+ALTER TABLE users ADD COLUMN email VARCHAR(255) NULL;
+
+-- Rename instead of drop
+ALTER TABLE old_users RENAME TO archived_users;
+
+-- Keep old column until new code deployed
+-- (multi-phase approach)
+```
+
+## Rollback Strategy
+
+```sql
+-- Every migration needs DOWN
+-- UP
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+
+-- DOWN
+ALTER TABLE users DROP COLUMN full_name;
+```
+
+## Remember
+- Test migrations on copy of production data
+- Have rollback plan ready
+- Monitor during deployment
+- Communicate with team about schema changes
+- Keep migrations small and focused

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

@@ -0,0 +1,152 @@
+---
+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: 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
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+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 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
+
+**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
+
+```
+NEVER FIX JUST WHERE THE ERROR APPEARS
+ALWAYS TRACE BACK TO FIND THE ORIGINAL TRIGGER
+```
+
+Fixing symptoms creates bandaid solutions that mask root problems.
+
+## Core Principles
+
+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
+
+### The 5-Step Trace Process
+
+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
+
+### Decision Tree
+
+```
+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)
+```
+
+## The Tracing Process
+
+**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
+```
+
+**At each level ask:** Where did this value come from? Is this the origin?
+
+**For detailed tracing methodology, see [Tracing Techniques](references/tracing-techniques.md)**
+**For complete real-world examples, see [Examples](references/examples.md)**
+
+## After Finding Root Cause
+
+**Fix at source** (throw if accessed before initialization) + **Add defense-in-depth** (validate at Project.create, WorkspaceManager, environment guards, instrumentation).
+
+This prevents similar bugs and catches issues earlier.
+
+## 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
+- 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)
+
+## Red Flags - STOP
+
+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
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- 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.