claude-mpm 4.21.3__py3-none-any.whl → 5.0.2__py3-none-any.whl

claude_mpm/skills/bundled/collaboration/dispatching-parallel-agents/references/examples.md

@@ -1,537 +0,0 @@
-# Examples
-
-Real-world scenarios, case studies, and time savings analysis from parallel agent dispatch.
-
-## Case Study 1: Test Suite Recovery
-
-**Scenario:** Major refactoring broke 6 tests across 3 files
-
-### Initial State
-
-```
-❌ agent-tool-abort.test.ts - 3 failures
-   - "should abort tool with partial output capture"
-   - "should handle mixed completed and aborted tools"
-   - "should properly track pendingToolCount"
-
-❌ batch-completion-behavior.test.ts - 2 failures
-   - "should execute all tools in batch"
-   - "should complete batch when all tools finish"
-
-❌ tool-approval-race-conditions.test.ts - 1 failure
-   - "should handle rapid tool approvals"
-```
-
-### Decision Process
-
-**Question 1:** Are these failures related?
-- Abort logic is independent of batch completion
-- Batch completion is independent of approval flow
-- Each test file tests different subsystem
-- **Answer:** Independent failures ✓
-
-**Question 2:** Can they be fixed in parallel?
-- No shared files being modified
-- Each domain has clear boundaries
-- Fixes won't interfere with each other
-- **Answer:** Yes, parallel dispatch appropriate ✓
-
-**Question 3:** Is overhead worth it?
-- 3 problem domains, would take ~20 min each sequentially = 60 min
-- Parallel: ~20 min total + 5 min integration = 25 min
-- **Answer:** Yes, saves 35 minutes ✓
-
-### Execution
-
-**Agent 1 Task:**
-```markdown
-Fix agent-tool-abort.test.ts failures (3 tests)
-Focus: Timing/race conditions in abort implementation
-```
-
-**Agent 2 Task:**
-```markdown
-Fix batch-completion-behavior.test.ts failures (2 tests)
-Focus: Event emission after architecture refactoring
-```
-
-**Agent 3 Task:**
-```markdown
-Fix tool-approval-race-conditions.test.ts failure (1 test)
-Focus: Async execution waiting
-```
-
-### Results
-
-**Agent 1 Findings:**
-- Root cause: Tests used arbitrary timeouts (100ms, 200ms)
-- Real issue: Event timing varies, timeouts are flaky
-- Fix: Replaced timeouts with event-based waiting
-- Files changed: agent-tool-abort.test.ts only
-- All 3 tests now pass ✓
-
-**Agent 2 Findings:**
-- Root cause: Event payload structure changed in refactoring
-- Old: `{ toolId, result }`
-- New: `{ threadId, toolId, result }`
-- Fix: Updated event emission to include threadId
-- Files changed: batch-executor.ts, batch.service.ts
-- Both tests now pass ✓
-
-**Agent 3 Findings:**
-- Root cause: Test asserted immediately, async execution still pending
-- Fix: Added `await waitForExecutionComplete()` before assertions
-- Files changed: tool-approval-race-conditions.test.ts only
-- Test now passes ✓
-
-### Integration
-
-**Conflict check:**
-- Agent 1: Modified test file only
-- Agent 2: Modified production files (batch executor)
-- Agent 3: Modified test file only
-- **No overlaps detected** ✓
-
-**Full suite verification:**
-```bash
-npm test
-# All tests pass ✓
-# No new failures introduced ✓
-```
-
-**Time analysis:**
-- Sequential approach: 60 minutes (3 × 20 min)
-- Parallel approach: 25 minutes (20 min + 5 min integration)
-- **Time saved: 35 minutes (58% reduction)**
-
-### Lessons Learned
-
-1. **Independence validation was correct** - No hidden dependencies emerged
-2. **Scope boundaries held** - Agents didn't overlap files
-3. **Clear prompts produced clear outputs** - All agents returned usable summaries
-4. **Integration was trivial** - No conflicts to resolve
-
-## Case Study 2: Multi-Subsystem Bug Fix
-
-**Scenario:** Production incident affecting 3 subsystems
-
-### Initial State
-
-```
-Incident: User-reported issues across the platform
-
-Symptoms:
-- Users can't log in (Auth subsystem)
-- Payments failing after login (Payment subsystem)
-- Email confirmations not sending (Notification subsystem)
-```
-
-### Decision Process
-
-**Question 1:** Are these related?
-- Login issue is auth-specific
-- Payment failure might be due to login, or independent
-- Email issue seems independent
-- **Answer:** Unclear, need investigation ⚠️
-
-**Decision:** Don't dispatch immediately, investigate first
-
-### Investigation Phase
-
-```markdown
-Single agent task: Investigate all 3 issues for 15 minutes
-
-Goal: Determine if shared root cause or independent bugs
-
-Report back before we dispatch parallel fixes
-```
-
-**Investigation Result:**
-```
-Auth: Database connection pool exhausted
-Payments: Independent bug - Stripe API version mismatch
-Emails: Independent bug - SMTP credentials expired
-
-Root cause analysis:
-- Auth issue is systemic, affects all subsystems indirectly
-- Payment and email issues are independent of auth
-- BUT: Must fix auth first (it's blocking everything)
-```
-
-### Revised Strategy
-
-**Phase 1:** Fix auth (single agent, high priority)
-```markdown
-Fix database connection pool exhaustion in auth subsystem
-This is blocking other subsystems - highest priority
-```
-
-**Phase 2:** After auth fixed, dispatch parallel fixes
-```markdown
-Agent 1: Fix Stripe API version mismatch in payment subsystem
-Agent 2: Update SMTP credentials in notification subsystem
-```
-
-### Execution
-
-**Phase 1 Result:**
-- Auth agent fixed connection pooling configuration
-- All subsystems now accessible
-- Time: 20 minutes
-
-**Phase 2 Dispatch:**
-- Agent 1 and 2 worked in parallel
-- No dependencies between payment and email fixes
-- Time: 15 minutes each (parallel)
-
-**Total time:** 35 minutes (20 + 15)
-**Sequential time would have been:** 50 minutes (20 + 15 + 15)
-**Saved:** 15 minutes, but more importantly caught the systemic issue first
-
-### Lessons Learned
-
-1. **Investigation before dispatch is sometimes critical** - Avoided wasting time on symptoms
-2. **Hierarchical dispatch works well** - Fix blocker, then parallelize remaining work
-3. **Apparent independence can be misleading** - Auth was blocking payment/email indirectly
-4. **Flexible strategy beats rigid process** - Adapted approach based on findings
-
-## Case Study 3: Feature Development in Parallel
-
-**Scenario:** New feature requires changes across 3 modules
-
-### Initial State
-
-```
-Feature: Add two-factor authentication
-
-Required changes:
-- Auth module: Add 2FA verification logic
-- User module: Add 2FA preferences storage
-- API module: Add 2FA setup/verify endpoints
-```
-
-### Decision Process
-
-**Question 1:** Are these independent?
-- Auth verification logic is self-contained
-- User preferences storage is independent
-- API endpoints depend on both auth logic and user storage
-- **Answer:** Partially independent ⚠️
-
-**Strategy:** Parallel with coordination point
-
-### Execution
-
-**Phase 1:** Parallel development of independent pieces
-```markdown
-Agent 1: Implement 2FA verification logic (auth module)
-- QR code generation
-- TOTP token validation
-- Backup codes
-
-Agent 2: Implement 2FA preferences (user module)
-- Database schema for 2FA settings
-- Methods to enable/disable 2FA
-- Backup code storage
-```
-
-**Coordination Point:**
-```markdown
-Both agents complete and return:
-- Agent 1: Exposes verify2FA(userId, token) interface
-- Agent 2: Exposes get2FASettings(userId) interface
-
-Review: Verify interfaces are compatible before API integration
-```
-
-**Phase 2:** Sequential API development
-```markdown
-Agent 3: Implement API endpoints using Agent 1 & 2 interfaces
-- POST /auth/2fa/setup
-- POST /auth/2fa/verify
-- GET /auth/2fa/status
-
-This must be sequential - depends on previous work
-```
-
-### Results
-
-**Time breakdown:**
-- Phase 1 (parallel): 45 minutes for both agents
-- Coordination review: 5 minutes
-- Phase 2 (sequential): 30 minutes
-- **Total: 80 minutes**
-
-**Sequential would have been:**
-- Agent 1: 45 minutes
-- Agent 2: 40 minutes
-- Agent 3: 30 minutes
-- **Total: 115 minutes**
-
-**Saved: 35 minutes (30% reduction)**
-
-### Lessons Learned
-
-1. **Feature development can be parallelized** - Even with dependencies
-2. **Interface coordination is critical** - Reviewed compatibility before integration
-3. **Phased approach handles dependencies** - Parallel where possible, sequential where necessary
-4. **Clear interface contracts enable parallel work** - Agents didn't need to coordinate during implementation
-
-## Pattern Analysis
-
-### When Parallel Saves Time
-
-**High benefit scenarios:**
-```
-✓ Many independent problems (5+)
-✓ Each problem takes significant time (20+ min)
-✓ Clear boundaries between domains
-✓ Minimal coordination overhead
-✓ Low risk of conflicts
-
-Example: 5 test files failing, 30 min each = 150 min sequential
-Parallel: 30 min + 10 min integration = 40 min
-Savings: 110 minutes (73%)
-```
-
-**Marginal benefit scenarios:**
-```
-~ 2-3 problems
-~ Each takes 10-15 minutes
-~ Some shared boundaries
-~ Need coordination
-
-Example: 3 bugs, 15 min each = 45 min sequential
-Parallel: 15 min + 10 min integration/coordination = 25 min
-Savings: 20 minutes (44%)
-```
-
-**No benefit scenarios:**
-```
-✗ 1-2 quick problems (<10 min each)
-✗ Highly related problems (shared root cause)
-✗ Significant coordination needed
-✗ High conflict risk
-
-Example: 2 related bugs, 8 min each = 16 min sequential
-Parallel: 8 min + 15 min coordination overhead = 23 min
-Loss: -7 minutes
-```
-
-## Real-World Time Savings
-
-### Project A: Test Suite Maintenance
-
-**Context:** Weekly test maintenance for large codebase
-
-**Before parallel agents:**
-- 10-15 flaky tests per week
-- Fixed sequentially: 4-5 hours
-- Developer time: 1 person, full afternoon
-
-**After parallel agents:**
-- Same 10-15 flaky tests
-- Fixed in parallel: 1-1.5 hours
-- Developer time: 15 min dispatch + 15 min integration
-
-**Time saved per week:** 3 hours
-**Over 6 months:** ~75 hours saved
-
-### Project B: Post-Refactoring Fixes
-
-**Context:** Major refactoring broke 20+ tests
-
-**Sequential approach (previous experience):**
-- 1 developer, 2 full days (16 hours)
-- High context switching cost
-- Fatigue led to mistakes
-
-**Parallel approach (current):**
-- 5 agents, dispatched in 2 waves
-- Wave 1: 5 agents × 1 hour = 1 hour
-- Wave 2: 5 agents × 1 hour = 1 hour
-- Integration: 30 minutes
-- **Total: 2.5 hours**
-
-**Time saved:** 13.5 hours (84% reduction)
-**Quality improvement:** Fewer mistakes (fresh agent context each time)
-
-### Project C: Multi-Subsystem Feature
-
-**Context:** Payment system upgrade touching 8 modules
-
-**Sequential development estimate:**
-- 8 modules × 3 hours each = 24 hours
-- 3 full days
-
-**Parallel approach:**
-- Grouped into 4 independent domains
-- 4 agents × 3 hours = 3 hours
-- Integration and testing: 2 hours
-- **Total: 5 hours**
-
-**Time saved:** 19 hours (79% reduction)
-
-## Anti-Pattern Examples
-
-### Anti-Pattern: Premature Parallelization
-
-**Scenario:**
-```
-Developer: "I have 4 test failures, let me dispatch 4 agents immediately"
-
-Result:
-- Agent 1 discovers: Root cause is shared utility bug
-- Agents 2, 3, 4 all hit the same bug
-- All 4 agents report the same issue
-- Wasted 3 agents' work
-```
-
-**Better approach:**
-```
-1. Quick investigation (5 min)
-2. Identify shared root cause
-3. Single agent fixes shared utility
-4. All 4 tests pass
-Total: 15 minutes vs 40+ wasted
-```
-
-### Anti-Pattern: Over-Scoped Agents
-
-**Scenario:**
-```
-Agent prompt: "Fix all the auth issues"
-
-Result:
-- Agent doesn't know where to start
-- Changes 15 files
-- Introduces new bugs
-- Hard to review changes
-```
-
-**Better approach:**
-```
-3 focused agents:
-- Agent 1: Fix login.test.ts (5 tests)
-- Agent 2: Fix session.test.ts (3 tests)
-- Agent 3: Fix oauth.test.ts (4 tests)
-
-Each agent knows exactly what to do
-Changes are reviewable
-No new bugs introduced
-```
-
-### Anti-Pattern: Ignoring Dependencies
-
-**Scenario:**
-```
-Dispatch in parallel:
-- Agent 1: Update User model
-- Agent 2: Update Auth service (uses User model)
-- Agent 3: Update Profile service (uses User model)
-
-Result:
-- Agent 1 changes User interface
-- Agents 2 & 3 use old interface
-- Massive integration conflicts
-```
-
-**Better approach:**
-```
-Phase 1: Agent 1 updates User model
-Phase 2: Agents 2 & 3 in parallel update services
-No conflicts, clean integration
-```
-
-## Success Metrics
-
-### Quantitative Metrics
-
-**Time Efficiency:**
-```
-Efficiency = 1 - (Parallel Time / Sequential Time)
-
-Good: >60% (3+ independent problems)
-Acceptable: 40-60% (2-3 problems with some coordination)
-Poor: <40% (not worth parallelization overhead)
-```
-
-**Conflict Rate:**
-```
-Conflict Rate = Conflicts / Total Agents
-
-Excellent: 0% (no conflicts)
-Good: <10% (minor conflicts, easy resolution)
-Acceptable: 10-20% (some conflicts, manageable)
-Poor: >20% (significant coordination issues)
-```
-
-### Qualitative Metrics
-
-**Agent Output Quality:**
-- Clear summaries provided: ✓
-- Root causes identified: ✓
-- Changes well-documented: ✓
-- Verification performed: ✓
-
-**Integration Smoothness:**
-- No merge conflicts: ✓
-- Compatible changes: ✓
-- Full suite passes: ✓
-- No regression introduced: ✓
-
-## Calculation Examples
-
-### Example 1: Simple Parallelization
-
-```
-Sequential:
-- Problem A: 20 min
-- Problem B: 20 min
-- Problem C: 20 min
-Total: 60 min
-
-Parallel:
-- All 3 agents: 20 min (concurrent)
-- Integration: 5 min
-Total: 25 min
-
-Savings: 35 min (58%)
-```
-
-### Example 2: With Dependencies
-
-```
-Sequential:
-- Problem A (blocking): 30 min
-- Problem B (depends on A): 20 min
-- Problem C (depends on A): 20 min
-Total: 70 min
-
-Parallel:
-- Phase 1 - Agent A: 30 min
-- Phase 2 - Agents B & C: 20 min (concurrent)
-- Integration: 5 min
-Total: 55 min
-
-Savings: 15 min (21%)
-```
-
-### Example 3: Investigation + Fix
-
-```
-Sequential:
-- Investigate: 15 min
-- Fix problem A: 20 min
-- Fix problem B: 20 min
-- Fix problem C: 20 min
-Total: 75 min
-
-Parallel:
-- Investigate (single agent): 15 min
-- Based on findings, dispatch 3 agents: 20 min (concurrent)
-- Integration: 5 min
-Total: 40 min
-
-Savings: 35 min (47%)
-```