moai-workflow-tdd

# Test-Driven Development (TDD) Workflow

## Development Mode Configuration (CRITICAL)

[NOTE] This workflow is selected based on `.moai/config/sections/quality.yaml`:

```yaml
constitution:
  development_mode: tdd    # or ddd
```

**When to use this workflow**:
- `development_mode: tdd` → Use TDD (this workflow, default)
- `development_mode: ddd` → Use DDD instead (moai-workflow-ddd)

**Key distinction**:
- **TDD** (default): Test-first development for all work, including brownfield projects with pre-RED analysis
- **DDD**: Characterization-test-first for existing codebases with minimal test coverage

## Quick Reference

Test-Driven Development provides a disciplined approach for creating new functionality where tests define the expected behavior before implementation.

Core Cycle - RED-GREEN-REFACTOR:

- RED: Write a failing test that defines desired behavior
- GREEN: Write minimal code to make the test pass
- REFACTOR: Improve code structure while keeping tests green

When to Use TDD:

- Creating new functionality from scratch
- Building isolated modules with no existing dependencies
- When behavior specification drives development
- New API endpoints with clear contracts
- New UI components with defined behavior
- Greenfield projects (rare - usually Hybrid is better)

When NOT to Use TDD:

- Refactoring existing code (use DDD instead)
- When behavior preservation is the primary goal
- Legacy codebase without test coverage (use DDD first)
- When modifying existing files (consider Hybrid mode)

---

## Core Philosophy

### TDD vs DDD Comparison

TDD Approach:

- Cycle: RED-GREEN-REFACTOR
- Goal: Create new functionality through tests
- Starting Point: No code exists
- Test Type: Specification tests that define expected behavior
- Outcome: New working code with test coverage

DDD Approach:

- Cycle: ANALYZE-PRESERVE-IMPROVE
- Goal: Improve structure without behavior change
- Starting Point: Existing code with defined behavior
- Test Type: Characterization tests that capture current behavior
- Outcome: Better structured code with identical behavior

### Test-First Principle

The golden rule of TDD is that tests must be written before implementation code:

- Tests define the contract
- Tests document expected behavior
- Tests catch regressions immediately
- Implementation is driven by test requirements

---

## Implementation Guide

### Phase 1: RED - Write a Failing Test

The RED phase focuses on defining the desired behavior through a failing test.

#### Writing Effective Tests

Before writing any implementation code:

- Understand the requirement clearly
- Define the expected behavior in test form
- Write one test at a time
- Keep tests focused and specific
- Use descriptive test names that document behavior

#### Test Structure

Follow the Arrange-Act-Assert pattern:

- Arrange: Set up test data and dependencies
- Act: Execute the code under test
- Assert: Verify the expected outcome

#### Verification

The test must fail initially:

- Confirms the test actually tests something
- Ensures the test is not passing by accident
- Documents the gap between current and desired state

### Phase 2: GREEN - Make the Test Pass

The GREEN phase focuses on writing minimal code to satisfy the test.

#### Minimal Implementation

Write only enough code to make the test pass:

- Do not over-engineer
- Do not add features not required by tests
- Focus on correctness, not perfection
- Hardcode values if necessary (refactor later)

#### Verification

Run the test to confirm it passes:

- All assertions must succeed
- No other tests should break
- Implementation satisfies the test requirements

### Phase 3: REFACTOR - Improve the Code

The REFACTOR phase focuses on improving code quality while maintaining behavior.

#### Safe Refactoring

With passing tests as a safety net:

- Remove duplication
- Improve naming and readability
- Extract methods and classes
- Apply design patterns where appropriate

#### Continuous Verification

After each refactoring step:

- Run all tests
- If any test fails, revert immediately
- Commit when tests pass

---

## TDD Workflow Execution

### Standard TDD Session

When executing TDD through manager-develop:

Step 1 - Understand Requirements:

- Read SPEC document for feature scope
- Identify test cases from acceptance criteria
- Plan test implementation order

Step 2 - RED Phase:

- Write first failing test
- Verify test fails for the right reason
- Document expected behavior

Step 3 - GREEN Phase:

- Write minimal implementation
- Run test to verify it passes
- Move to next test

Step 4 - REFACTOR Phase:

- Review code for improvements
- Apply refactoring with tests as safety net
- Commit clean code

Step 5 - Repeat:

- Continue RED-GREEN-REFACTOR cycle
- Until all requirements are implemented
- Until all acceptance criteria pass

### TDD Loop Pattern

For features requiring multiple test cases:

- Identify all test cases upfront
- Prioritize by dependency and complexity
- Execute RED-GREEN-REFACTOR for each
- Maintain cumulative test suite

---

## Quality Metrics

### TDD Success Criteria

Test Coverage (Required):

- Minimum 80% coverage per commit
- 90% recommended for new code
- All public interfaces tested

Code Quality (Goals):

- All tests pass
- No test written after implementation
- Clear test names documenting behavior
- Minimal implementation satisfying tests

### TDD-Specific TRUST Validation

Apply TRUST 5 framework with TDD focus:

- Testability: Test-first approach ensures testability
- Readability: Tests document expected behavior
- Understandability: Tests serve as living documentation
- Security: Security tests written before implementation
- Transparency: Test failures provide immediate feedback

---

## Integration Points

### With DDD Workflow

TDD and DDD are complementary:

- TDD for new code
- DDD for existing code refactoring
- Hybrid mode combines both approaches

### With Testing Workflow

TDD integrates with testing workflow:

- Uses specifica