Plan to tdd

Plan-to-TDD

Transform feature plans → test-driven implementation using Outside-In methodology.

When to Use

Invoke when:

• Converting plan docs from docs/plan/YYYY/MM/ to code
• Designing test structure for new features
• Applying TDD w/ architectural awareness
• Bridging system design to implementation

Prerequisites

• Reference: .claude/skills/test-levels for Unit/Integration/E2E guidance
• Plan files in docs/plan/YYYY/MM/YYYY_MM_DD_HHmm__FEATURE_NAME.md

Related Skills

Skill	Location	Phase
doc-navigator	.claude/skills/doc-navigator	Load/Design - find existing patterns
uiux-toolkit	.claude/skills/uiux-toolkit	Verify - 9-domain UX evaluation
test-levels	.claude/skills/test-levels	Plan/Execute - test distribution

---

Outside-In Workflow

SYSTEM DESIGN → INTEGRATION TESTS (Red) → TDD UNITS → E2E VALIDATION

Phase Flow

┌─────────────────────────────────────────────────┐
│ 1. SYSTEM DESIGN                                │
│    Components → Contracts → Dependencies        │
└────────────────────┬────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────┐
│ 2. INTEGRATION TESTS (Red)                      │
│    Validate component contracts - tests FAIL    │
└────────────────────┬────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────┐
│ 3. TDD UNIT PHASE                               │
│    Red → Green → Refactor per unit              │
└────────────────────┬────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────┐
│ 4. E2E VALIDATION                               │
│    Complete user journey verification           │
└─────────────────────────────────────────────────┘

---

Execution Steps

Step 1: Load Plan

Input: docs/plan/YYYY/MM/YYYY_MM_DD_HHmm__FEATURE_NAME.md

Extract:

1. User story & acceptance criteria
2. Components & dependencies
3. Data flows
4. Technical constraints

Expected structure:

# Feature: [Name]

## User Story
As a [user], I want to [action] so that [benefit].

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Components
- Component A: Description
- Component B: Description

## Data Flow
1. Step 1
2. Step 2

Step 2: Define Contracts

For each component boundary:

interface [Component]Contract {
  input: {
    type: string;
    validation: string[];
    source: string; // sender component
  };
  output: {
    type: string;
    successCase: string;
    errorCases: string[];
  };
  dependencies: string[];
}

Step 3: Generate Tests

E2E Tests (Complete Car)

// tests/e2e/[feature].spec.ts
describe('[Feature] - User Journey', () => {
  test('User can [action] successfully', async () => {
    // Arrange → Act → Assert
  });
  test('User sees error when [condition]', async () => {
    // Error path from user perspective
  });
});

Integration Tests (Engine + Transmission)

// tests/integration/[component].test.ts
describe('[ComponentA] → [ComponentB]', () => {
  test('Contract: [description]', async () => {
    // Validates the "arrow" in system design
  });
  test('Handles timeout gracefully', async () => {
    // Test architectural assumptions
  });
});

Unit Tests (Individual Parts)

// tests/unit/[module].test.ts
describe('[Module]', () => {
  test('returns [expected] when [condition]', () => {
    // Red → Green → Refactor
  });
  test('throws [error] when [invalid input]', () => {
    // Edge cases
  });
});

Step 4: Implementation Order

1. Scaffold        Create files & empty interfaces
       ↓
2. E2E (Red)       Failing E2E for user journey
       ↓
3. Integration     For each boundary:
   (Red)           - Failing integration test
                   - Validates contract
       ↓
4. TDD Cycle       For each unit:
   (Red→Green→     - Failing unit test
    Refactor)      - Min code to pass
                   - Refactor for clarity
       ↓
5. Integration     Run integration (should pass)
   (Green)
       ↓
6. E2E (Green)     Run E2E (should pass)
       ↓
7. Refactor        Clean up, optimize

---

The Bridge: Design → Mocks

System design arrow becomes mock:

┌─────────────┐    ┌─────────────┐
│ OrderService│───▶│InventorySvc│
└─────────────┘    └─────────────┘

const mockInventoryService = {
  checkStock: jest.fn(),
};

describe('OrderService', () => {
  test('throws OutOfStockException when inventory = 0', () => {
    mockInventoryService.checkStock.mockReturnValue(0);
    expect(() => orderService.placeOrder(item))
      .toThrow(OutOfStockException);
  });
});

Key insight: TDD validates architectural contracts:

• Timeouts in design → Test timeout handling
• Error responses → Test error handling
• Data transforms → Test transformations

---

Test Pain → Design Fix

Pain Signal	Design Issue	Fix
50+ lines mock setup	Too coupled	Split into smaller services
Needs real DB	Missing abstraction	Add repository interface
Can't test isolated	Circular deps	Restructure dependency graph
Brittle tests	Leaky abstractions	Strengthen contracts

When pain detected:

1. Stop coding
2. Document the pain
3. Return to design
4. Refactor architecture
5. Resume TDD

---

Output Artifacts

Generate in /docs/features/[feature]/:

• DESIGN.md - System design doc
• CONTRACTS.md - Interface contracts
• TEST-PLAN.md - Test structure & order
• IMPLEMENTATION.md - Build plan w/ tasks

---

Quick Reference

# Load & parse plan
/load-plan [plan-path]

# Extract components
/extract-components [plan-path]

# Generate contracts
/define-contracts [plan-path]

# Generate test scaffolds
/generate-tests [plan-path]

# Start TDD w/ first red test
/tdd-start [plan-path]

# List plans
/list-plans
/list-plans --month 2024-03

---

Test Distribution (from test-levels)

Level	Question	Location
Unit	"Does this fn work?"	tests/unit/
Integration	"Do parts connect?"	tests/integration/
E2E	"Does flow work?"	tests/e2e/

Pyramid: Many unit → Some integration → Few E2E