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

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

@@ -1,458 +0,0 @@
-# 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