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

claude_mpm/skills/bundled/testing/condition-based-waiting/references/patterns-and-implementation.md

@@ -0,0 +1,253 @@
+# Detailed Patterns and Implementation Guide
+
+This reference provides detailed implementation patterns, common mistakes, and edge cases for condition-based waiting.
+
+## Common Mistakes
+
+### ❌ Polling too fast
+```typescript
+// BAD: Wastes CPU
+await new Promise(r => setTimeout(r, 1));
+```
+
+**✅ Fix:** Poll every 10ms
+```typescript
+await new Promise(r => setTimeout(r, 10)); // Balanced interval
+```
+
+### ❌ No timeout
+```typescript
+// BAD: Loop forever if condition never met
+while (true) {
+  const result = condition();
+  if (result) return result;
+  await new Promise(r => setTimeout(r, 10));
+}
+```
+
+**✅ Fix:** Always include timeout with clear error
+```typescript
+const startTime = Date.now();
+while (true) {
+  const result = condition();
+  if (result) return result;
+
+  if (Date.now() - startTime > timeoutMs) {
+    throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+  }
+
+  await new Promise(r => setTimeout(r, 10));
+}
+```
+
+### ❌ Stale data
+```typescript
+// BAD: Cache state before loop
+const state = machine.getState();
+await waitFor(() => state === 'ready'); // state never updates!
+```
+
+**✅ Fix:** Call getter inside loop for fresh data
+```typescript
+await waitFor(() => machine.getState() === 'ready'); // Fresh on each poll
+```
+
+## When Arbitrary Timeout IS Correct
+
+There are legitimate cases where a fixed timeout is the right approach:
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**Requirements for justified arbitrary timeouts:**
+1. First wait for triggering condition (condition-based wait comes first)
+2. Based on known timing (not guessing - actual system tick rate)
+3. Comment explaining WHY timeout is necessary
+
+## Advanced Patterns
+
+### Waiting with transformation
+```typescript
+// Wait for event and return transformed data
+const userId = await waitFor(
+  () => events.find(e => e.type === 'USER_CREATED')?.data.id,
+  'user creation event'
+);
+```
+
+### Waiting with complex conditions
+```typescript
+// Multiple conditions must be met
+await waitFor(
+  () => {
+    const user = getUser();
+    return user?.verified && user?.credits > 0 ? user : undefined;
+  },
+  'verified user with credits'
+);
+```
+
+### Waiting with side effects
+```typescript
+// Log attempts while waiting
+let attempts = 0;
+await waitFor(
+  () => {
+    attempts++;
+    if (attempts % 10 === 0) {
+      console.log(`Still waiting after ${attempts} attempts...`);
+    }
+    return isReady() || undefined;
+  },
+  'system ready'
+);
+```
+
+### Waiting with custom timeouts per condition
+```typescript
+// Different timeouts for different scenarios
+async function waitForDeploy(environment: string) {
+  const timeout = environment === 'prod' ? 30000 : 5000;
+  return waitFor(
+    () => checkDeployStatus(environment),
+    `${environment} deployment`,
+    timeout
+  );
+}
+```
+
+## Domain-Specific Helpers
+
+When you have common waiting scenarios, create domain-specific helpers:
+
+```typescript
+// Event-based waiting
+async function waitForEvent(
+  manager: EventManager,
+  eventType: string,
+  timeoutMs = 5000
+) {
+  return waitFor(
+    () => manager.getEvents().find(e => e.type === eventType),
+    `event ${eventType}`,
+    timeoutMs
+  );
+}
+
+// Count-based waiting
+async function waitForEventCount(
+  manager: EventManager,
+  minCount: number,
+  timeoutMs = 5000
+) {
+  return waitFor(
+    () => {
+      const events = manager.getEvents();
+      return events.length >= minCount ? events : undefined;
+    },
+    `at least ${minCount} events`,
+    timeoutMs
+  );
+}
+
+// Pattern matching waiting
+async function waitForEventMatch(
+  manager: EventManager,
+  matcher: (event: Event) => boolean,
+  timeoutMs = 5000
+) {
+  return waitFor(
+    () => manager.getEvents().find(matcher),
+    'event matching predicate',
+    timeoutMs
+  );
+}
+```
+
+See @example.ts for complete working implementations from real debugging session.
+
+## Debugging Tips
+
+### Add descriptive error messages
+```typescript
+// GOOD: Clear what failed
+await waitFor(
+  () => orders.find(o => o.status === 'SHIPPED'),
+  'order to be shipped',
+  5000
+);
+// Error: "Timeout waiting for order to be shipped after 5000ms"
+
+// BETTER: Include context
+await waitFor(
+  () => orders.find(o => o.id === orderId && o.status === 'SHIPPED'),
+  `order ${orderId} to be shipped`,
+  5000
+);
+// Error: "Timeout waiting for order abc-123 to be shipped after 5000ms"
+```
+
+### Log current state on timeout
+```typescript
+async function waitForWithDebug<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  getCurrentState: () => any,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      const state = getCurrentState();
+      throw new Error(
+        `Timeout waiting for ${description} after ${timeoutMs}ms. ` +
+        `Current state: ${JSON.stringify(state)}`
+      );
+    }
+
+    await new Promise(r => setTimeout(r, 10));
+  }
+}
+```
+
+## Performance Considerations
+
+### Poll interval trade-offs
+- **1ms**: Too fast, wastes CPU (10,000 checks/second)
+- **10ms**: Good default, responsive (100 checks/second)
+- **50ms**: Acceptable for slow operations (20 checks/second)
+- **100ms+**: Only for very slow operations or known timing
+
+### Choose appropriate timeout values
+```typescript
+// Fast operations - short timeout
+await waitFor(() => cache.get(key), 'cache hit', 1000);
+
+// Network operations - medium timeout
+await waitFor(() => fetchStatus(), 'API response', 5000);
+
+// External systems - long timeout
+await waitFor(() => checkDeployment(), 'deployment complete', 30000);
+```
+
+### Avoid expensive condition checks
+```typescript
+// BAD: Expensive regex on every poll
+await waitFor(() => /complex.*regex.*pattern/.test(getLargeString()), ...);
+
+// GOOD: Cache expensive computations
+let parsed;
+await waitFor(() => {
+  const str = getString();
+  parsed = parsed || expensiveParse(str);
+  return parsed.isReady;
+}, ...);
+```

claude_mpm/skills/bundled/testing/test-driven-development/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: test-driven-development
+description: Write the test first, watch it fail, write minimal code to pass
+version: 3.2.0
+category: testing
+author: Jesse Vincent
+license: MIT
+source: https://github.com/obra/superpowers-skills/tree/main/skills/testing/test-driven-development
+progressive_disclosure:
+  entry_point:
+    summary: "Enforce test-first development with strict RED/GREEN/REFACTOR cycle. Never write implementation before failing test."
+    when_to_use: "When implementing any feature or bugfix, before writing implementation code. Always for new features, bug fixes, refactoring, and behavior changes."
+    quick_start: "1. Write failing test 2. Watch it fail (verify) 3. Write minimal code to pass 4. Watch it pass (verify) 5. Refactor if needed 6. Repeat"
+  references:
+    - workflow.md
+    - examples.md
+    - philosophy.md
+    - anti-patterns.md
+    - integration.md
+context_limit: 800
+tags:
+  - tdd
+  - testing
+  - red-green-refactor
+  - test-first
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+This skill enforces strict test-first development following the RED/GREEN/REFACTOR cycle. Violating the letter of the rules is violating the spirit of the rules.
+
+## When to Use This Skill
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask human partner):**
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+
+## Core Principles
+
+1. **RED**: Write a failing test first
+2. **GREEN**: Write minimal code to make test pass
+3. **REFACTOR**: Improve code while keeping tests green
+4. **NEVER**: Write implementation before tests
+
+## Quick Start
+
+### The RED/GREEN/REFACTOR Cycle
+
+```
+RED → Verify RED → GREEN → Verify GREEN → REFACTOR → Repeat
+```
+
+1. **RED**: Write one minimal test showing desired behavior
+2. **Verify RED**: Run test, confirm it fails for right reason
+3. **GREEN**: Write simplest code to pass test
+4. **Verify GREEN**: Run test, confirm it passes
+5. **REFACTOR**: Clean up while keeping tests green
+6. **Repeat**: Next test for next feature
+
+## Cycle Details
+
+**RED**: Write one minimal test (one behavior, clear name, real code)
+**Verify RED**: MANDATORY - watch it fail for right reason
+**GREEN**: Write simplest code to pass (no extras)
+**Verify GREEN**: MANDATORY - watch it pass, all tests pass
+**REFACTOR**: Clean up while keeping tests green (optional)
+
+## Navigation
+
+For detailed information:
+- **[Workflow](references/workflow.md)**: Complete RED/GREEN/REFACTOR workflow with detailed examples
+- **[Examples](references/examples.md)**: Real-world TDD scenarios with step-by-step walkthroughs
+- **[Philosophy](references/philosophy.md)**: Why order matters and why tests-after don't work
+- **[Anti-patterns](references/anti-patterns.md)**: Common mistakes, rationalizations, and red flags
+- **[Integration](references/integration.md)**: Using TDD with debugging and other skills
+
+## Key Reminders
+
+- ALWAYS write the test BEFORE implementation
+- Make each test fail FIRST to verify it's testing something
+- Keep implementation minimal - just enough to pass tests
+- Refactor only when tests are green
+- One cycle at a time - small steps
+- If test passes immediately, it's not testing new behavior
+
+## Red Flags - STOP and Start Over
+
+If you catch yourself:
+- Writing code before test
+- Test passes immediately
+- Can't explain why test failed
+- "I'll test after"
+- "Keep as reference"
+- "Already spent X hours, deleting is wasteful"
+- "Tests after achieve the same purpose"
+
+**ALL of these mean: Delete code. Start over with TDD.**
+
+## Why Order Matters
+
+Tests-after pass immediately (proves nothing), test-first fail then pass (proves it works). See [Philosophy](references/philosophy.md) for detailed explanation.
+
+## Integration with Other Skills
+
+- **systematic-debugging**: Create failing test in Phase 4 (bug reproduction)
+- **verification-before-completion**: Verify tests exist and watched them fail
+- **defense-in-depth**: Add validation tests after implementing feature
+
+## Real-World Impact
+
+From TDD practice:
+- Test-first: 95%+ first-time correctness
+- Test-after: 40% first-time correctness
+- TDD time: 25-45 minutes per feature (including tests)
+- Non-TDD time: 15 minutes coding + 60-120 minutes debugging
+
+**TDD is pragmatic** - finds bugs before commit, prevents regressions, documents behavior, enables refactoring.