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

claude_mpm/skills/bundled/testing/test-driven-development/references/philosophy.md

@@ -0,0 +1,458 @@
+# TDD Philosophy: Why Order Matters
+
+> **Part of**: [Test-Driven Development](../SKILL.md)
+> **Category**: testing
+> **Reading Level**: Advanced
+
+## Purpose
+
+Deep dive into why test-first development works and why tests-after fundamentally cannot achieve the same benefits, despite appearing similar.
+
+## The Core Question
+
+**"Why can't I write tests after? I'll still have 100% coverage."**
+
+This question misunderstands what TDD provides. Coverage is the least important benefit.
+
+## What Tests-First Actually Provides
+
+### 1. Design Feedback
+
+**Test-First:**
+```typescript
+// Write test first
+test('calculates shipping cost', () => {
+  const cost = calculateShipping({ weight: 10, distance: 500 });
+  expect(cost).toBe(25);
+});
+
+// Forces you to design a clean API
+// - What parameters does it need?
+// - What does it return?
+// - Is it easy to call?
+```
+
+**Test-After:**
+```typescript
+// Write implementation first
+function calculateShipping(order: Order) {
+  const baseRate = config.shipping.baseRate;
+  const weightFactor = config.shipping.weightFactor;
+  const distanceFactor = config.shipping.distanceFactor;
+  const specialHandling = order.items.some(i => i.fragile);
+  // ... complex logic
+  return cost;
+}
+
+// Write test for what you built
+test('calculates shipping cost', () => {
+  const order = createComplexOrderObject();
+  const cost = calculateShipping(order);
+  expect(cost).toBeGreaterThan(0);  // Vague assertion
+});
+
+// Test accepts complex API because implementation already exists
+```
+
+**Outcome:**
+- **Test-First**: Simple, clean API emerged from test
+- **Test-After**: Complex API accepted because changing implementation is "wasteful"
+
+### 2. Requirements Verification
+
+**Test-First:**
+```typescript
+// Test defines requirement
+test('rejects invalid email format', () => {
+  const result = validateEmail('invalid');
+  expect(result.valid).toBe(false);
+  expect(result.error).toBe('Invalid email format');
+});
+
+// Implementation must satisfy exact requirement
+// Can't "forget" edge cases - test will fail
+```
+
+**Test-After:**
+```typescript
+// Implement based on memory
+function validateEmail(email: string) {
+  return email.includes('@');  // Forgot other validations
+}
+
+// Write test for what you remembered to implement
+test('validates email', () => {
+  expect(validateEmail('user@example.com')).toBe(true);
+  expect(validateEmail('invalid')).toBe(false);
+  // Didn't test: multiple @, domain validation, etc.
+});
+
+// Test passes, but incomplete
+```
+
+**Outcome:**
+- **Test-First**: Test drives complete implementation
+- **Test-After**: Test verifies what you remembered
+
+### 3. Proof of Test Quality
+
+**Test-First:**
+```typescript
+// RED: Write test, watch it fail
+test('retries on failure', async () => {
+  const result = await withRetry(failingOperation);
+  expect(result).toBe('success');
+});
+
+// RUN: See failure
+// FAIL: withRetry is not defined
+
+// You KNOW test works because you saw it fail
+```
+
+**Test-After:**
+```typescript
+// Write implementation
+async function withRetry(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    return await fn();
+  }
+}
+
+// Write test
+test('retries on failure', async () => {
+  const result = await withRetry(succeedingOperation);
+  expect(result).toBe('success');
+});
+
+// RUN: Test passes immediately
+// PASS ✓
+
+// But test is broken! It never fails, so it tests nothing.
+```
+
+**Outcome:**
+- **Test-First**: Watched fail → know it works
+- **Test-After**: Passes immediately → might be broken
+
+## Why "Tests-After Achieve Same Goals" Is Wrong
+
+### Claim: "Tests-after give same coverage"
+
+**Reality**: Coverage measures lines executed, not correctness verified.
+
+```typescript
+// 100% coverage, useless test
+function add(a: number, b: number): number {
+  return a - b;  // BUG: subtraction instead of addition
+}
+
+test('add function', () => {
+  add(2, 3);  // Executes line = 100% coverage
+  // But doesn't verify result!
+});
+```
+
+**Coverage is not quality.**
+
+### Claim: "I test all edge cases after implementation"
+
+**Reality**: You test edge cases you remember. Test-first discovers edge cases.
+
+```typescript
+// Test-first: Edge cases emerge naturally
+
+// RED: Basic case
+test('processes single item', () => {
+  expect(process([item])).toEqual([processed]);
+});
+
+// GREEN: Implement
+function process(items) {
+  return items.map(transform);
+}
+
+// RED: What about empty?
+test('processes empty array', () => {
+  expect(process([])).toEqual([]);
+});
+// Forces you to think about edge case
+
+// Test-after: Edge cases you remember
+function process(items) {
+  return items.map(transform);
+}
+
+test('processes array', () => {
+  expect(process([item])).toEqual([processed]);
+  // Forgot empty array - test never forced you to consider it
+});
+```
+
+### Claim: "30 minutes of tests-after is same as TDD"
+
+**Reality**: The difference is what happens during those 30 minutes.
+
+**Test-First 30 Minutes:**
+1. Write test defining behavior (5 min)
+2. Watch it fail - verify test works (1 min)
+3. Implement to pass test (10 min)
+4. Watch it pass - verify implementation works (1 min)
+5. Refactor safely with tests (8 min)
+6. Next feature (5 min)
+
+**Result**: 5 behaviors implemented, all tested, refactored
+
+**Test-After 30 Minutes:**
+1. Implement all 5 behaviors (20 min)
+2. Write tests for what you built (10 min)
+3. All tests pass immediately
+4. Hope you didn't forget anything
+
+**Result**: 5 behaviors implemented, tests of unknown quality
+
+### Claim: "It's about spirit, not ritual"
+
+**Reality**: The "spirit" is discovered through the "ritual."
+
+The spirit of TDD is:
+- Let tests drive design
+- Verify requirements incrementally
+- Get immediate feedback
+- Build confidence through observation
+
+You cannot achieve this spirit without the ritual:
+- Test must fail first (drives design)
+- Implementation must be minimal (incremental)
+- Test must pass after (immediate feedback)
+- You must watch both (builds confidence)
+
+**Analogy**: "I understand the spirit of weightlifting, so I'll visualize lifting weights instead of actually lifting them."
+
+The spirit emerges from the practice, not from understanding the principles.
+
+## The Sunk Cost Fallacy
+
+### Situation
+```
+You: "I've already written 500 lines of implementation"
+Partner: "Write tests first, delete that code"
+You: "But I spent 4 hours on it! Deleting is wasteful!"
+```
+
+### Analysis
+
+**Time already spent:** 4 hours (GONE, cannot recover)
+
+**Option A: Keep it and test after**
+- Time: 4 hours (sunk) + 30 min (tests)
+- Result: Code of unknown quality, weak tests
+- Future: Likely 2-4 hours debugging issues
+- Total: 6.5-8.5 hours
+
+**Option B: Delete and TDD**
+- Time: 4 hours (sunk) + 2 hours (TDD rewrite)
+- Result: Clean code, strong tests
+- Future: Minimal debugging
+- Total: 6 hours
+
+**Option B is objectively better despite feeling worse.**
+
+### Psychological Trap
+
+The 4 hours feel "wasted" if you delete code.
+
+But:
+- Those 4 hours taught you about the problem
+- Rewrite with TDD will be faster (you understand it now)
+- Quality will be higher
+- You avoid future debugging time
+
+**The 4 hours weren't wasted - they were learning.**
+
+## The Pragmatism Argument
+
+### Claim: "TDD is dogmatic, pragmatism means adapting to situation"
+
+**Reality**: TDD IS pragmatic. Tests-after is optimistic gambling.
+
+**Pragmatic Question**: Which approach has better ROI?
+
+**Test-First:**
+- Time: 30 min (test + implementation)
+- Bugs found: Before commit
+- Debugging time: ~5 min (test tells you exactly what broke)
+- Regression risk: Near zero
+- Refactoring confidence: High
+- Total time: ~35 min
+
+**Test-After:**
+- Time: 20 min (implementation) + 10 min (tests)
+- Bugs found: In production (maybe)
+- Debugging time: 60-120 min (investigate what broke)
+- Regression risk: Medium
+- Refactoring confidence: Low
+- Total time: 90-150 min
+
+**Which is pragmatic?**
+
+### Real-World Data
+
+From industry studies and team observations:
+
+```
+TDD Projects:
+- 40-80% fewer bugs in production
+- 15-35% more development time upfront
+- 50-90% less debugging time
+- Net: 20-40% less total time
+
+Non-TDD Projects:
+- More bugs in production
+- Less development time upfront
+- Significantly more debugging time
+- Net: More total time, lower quality
+```
+
+**"Pragmatic" shortcuts = long-term waste**
+
+## The Manual Testing Trap
+
+### Claim: "I already manually tested all edge cases"
+
+**Problems:**
+
+**1. Manual testing is unreliable**
+```
+You test:
+- Happy path
+- One error case
+- Edge case you thought of
+
+You forget:
+- Edge cases you didn't think of
+- Error cases you didn't encounter
+- Combinations of conditions
+```
+
+**2. Manual testing doesn't scale**
+```
+Feature A: 5 min manual test
+Feature B: 5 min manual test
+Feature C: 5 min manual test
+
+After Feature C:
+To test everything: 15 min
+After Feature Z: 130 min
+After refactoring: 130 min AGAIN
+```
+
+**3. Manual testing has no record**
+```
+You: "I tested this"
+Later: "Did you test X condition?"
+You: "I think so? Maybe?"
+No proof, must test again
+```
+
+**Automated tests:**
+- Run in seconds
+- Test exact same way every time
+- Permanent record of what's tested
+- Run on every change
+
+## The "Just This Once" Trap
+
+### Pattern
+
+```
+Situation 1: "This is simple, skip TDD just this once"
+Situation 2: "This is urgent, skip TDD just this once"
+Situation 3: "This is exploratory, skip TDD just this once"
+Situation 4: "This is a bug fix, skip TDD just this once"
+```
+
+**Result**: TDD never happens
+
+### Reality Check
+
+**Every situation has an excuse:**
+- Simple → "Not worth testing"
+- Complex → "Too hard to test"
+- Urgent → "No time to test"
+- Exploratory → "Will throw away anyway"
+- Bug fix → "Just need quick fix"
+
+**All excuses are wrong:**
+- Simple code breaks
+- Complex code NEEDS tests
+- Urgent code needs to be correct
+- Exploration teaches you what to test
+- Bug fixes need regression protection
+
+## What Tests-First Actually Feels Like
+
+### Common Experience
+
+**Week 1-2: Frustrating**
+- Feels slower
+- Fighting the process
+- "Why can't I just write the code?"
+
+**Week 3-4: Understanding**
+- Starting to see benefits
+- Tests catch bugs before commit
+- Less debugging time
+
+**Week 5+: Natural**
+- Can't imagine coding without tests first
+- Feels faster than old way
+- Confidence in changes
+
+### The Shift
+
+**Before TDD:**
+```
+Write code → Run → Debug → Fix → Run → Debug → Fix → Done?
+Anxiety: "Did I break anything?"
+```
+
+**After TDD:**
+```
+Write test → Watch fail → Write code → Watch pass → Done!
+Confidence: "All tests green = definitely works"
+```
+
+## Summary
+
+### Tests-First ≠ Tests-After Because:
+
+1. **Design**: Test-first drives clean design
+2. **Requirements**: Test-first discovers edge cases
+3. **Proof**: Test-first proves tests work
+4. **Feedback**: Test-first gives immediate feedback
+5. **Confidence**: Test-first builds real confidence
+
+### Common Misconceptions:
+
+- ✗ "Coverage is the goal" → Quality is the goal
+- ✗ "Tests-after are equivalent" → Fundamentally different
+- ✗ "Deleting code is wasteful" → Sunk cost fallacy
+- ✗ "TDD is dogmatic" → TDD is pragmatic
+- ✗ "Manual testing suffices" → Doesn't scale or persist
+- ✗ "Just this once" → Becomes every time
+
+### The Truth:
+
+**TDD takes discipline but saves time.**
+**Tests-after feels faster but wastes time.**
+**The only way to understand is to practice TDD properly for 30 days.**
+
+## Related References
+
+- [Workflow](workflow.md): How to practice TDD
+- [Examples](examples.md): Real-world scenarios
+- [Anti-patterns](anti-patterns.md): Common mistakes
+- [Integration](integration.md): TDD with other skills