claude-mpm 5.4.41__py3-none-any.whl → 5.6.23__py3-none-any.whl

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

@@ -0,0 +1,537 @@
+# 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%)
+```