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:

User story & acceptance criteria
Components & dependencies
Data flows
Technical constraints

Expected structure:

markdown

# 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:

typescript

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)

typescript

// 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)

typescript

// 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)

typescript

// 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│
└─────────────┘    └─────────────┘

typescript

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:

Stop coding
Document the pain
Return to design
Refactor architecture
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

bash

# 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

Search AI Tools

plan-to-tdd

Install this agent skill to your Project

SKILL.md

Plan-to-TDD

When to Use

Prerequisites

Related Skills

Outside-In Workflow

Phase Flow

Execution Steps

Step 1: Load Plan

Step 2: Define Contracts

Step 3: Generate Tests

E2E Tests (Complete Car)

Integration Tests (Engine + Transmission)

Unit Tests (Individual Parts)

Step 4: Implementation Order

The Bridge: Design → Mocks

Test Pain → Design Fix

Output Artifacts

Quick Reference

Test Distribution (from test-levels)