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

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,177 @@
+---
+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
+languages: all
+---
+
+# 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.
+
+## 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";
+}
+```
+
+**Use 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
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 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!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```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,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script: @find-polluter.sh
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+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";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**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
+
+## 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

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