---
description: Execute full TDD red-green-refactor cycle with validation gates. Use when saying "TDD cycle", "test-driven development", or "full TDD workflow".
version: 1.0.0
---

# TDD Cycle - Comprehensive Test-Driven Development

## --phase Flag (v1.1.0+)

`sw:tdd-cycle` supports a `--phase` flag to run a single phase of the RED → GREEN → REFACTOR cycle. Omitting the flag (or passing `--phase all`) runs the full cycle.

| Flag | Behavior |
|------|----------|
| `--phase all` (default) | Full RED → GREEN → REFACTOR cycle. Same as omitting the flag. |
| `--phase red` | Runs only the RED phase — write failing tests. See Phase 2 below. |
| `--phase green` | Runs only the GREEN phase — write minimal code to make tests pass. See Phase 3 below. |
| `--phase refactor` | Runs only the REFACTOR phase — improve code quality with tests as safety net. See Phase 4 below. |

### Alias routing from deprecated skills

The following deprecated single-phase skills are aliased in `marketplace.json` to route through `sw:tdd-cycle --phase <x>`:

- `/sw:tdd-red` → `/sw:tdd-cycle --phase red`
- `/sw:tdd-green` → `/sw:tdd-cycle --phase green`
- `/sw:tdd-refactor` → `/sw:tdd-cycle --phase refactor`

The aliases emit a one-time migration warning pointing users to the canonical `--phase` form. The three `tdd-*` skills are scheduled for removal in v1.3.0 — see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.

### Examples

```bash
# Full cycle (default)
sw:tdd-cycle "user authentication"

# Single phases
sw:tdd-cycle --phase red "user authentication"
sw:tdd-cycle --phase green "user authentication"
sw:tdd-cycle --phase refactor "user authentication"

# Same as default — explicit
sw:tdd-cycle --phase all "user authentication"
```

---

## Project Overrides

**Skill Memories**: If `.specweave/skill-memories/tdd-cycle.md` exists, read and apply its learnings.

Execute a comprehensive Test-Driven Development (TDD) workflow with strict red-green-refactor discipline:

[Extended thinking: This workflow enforces test-first development through coordinated agent orchestration. Each phase of the TDD cycle is strictly enforced with fail-first verification, incremental implementation, and continuous refactoring. The workflow supports both single test and test suite approaches with configurable coverage thresholds.]

## Configuration

### Coverage Thresholds
- Minimum line coverage: 80%
- Minimum branch coverage: 75%
- Critical path coverage: 100%

### Refactoring Triggers
- Cyclomatic complexity > 10
- Method length > 20 lines
- Class length > 200 lines
- Duplicate code blocks > 3 lines

## Phase 1: Test Specification and Design

### 1. Requirements Analysis
- Use Task tool with subagent_type="Plan"
- Prompt: "Analyze requirements for: $ARGUMENTS. Define acceptance criteria, identify edge cases, and create test scenarios. Output a comprehensive test specification."
- Output: Test specification, acceptance criteria, edge case matrix
- Validation: Ensure all requirements have corresponding test scenarios

### 2. Test Architecture Design
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Design test architecture for: $ARGUMENTS based on test specification. Define test structure, fixtures, mocks, and test data strategy. Ensure testability and maintainability."
- Output: Test architecture, fixture design, mock strategy
- Validation: Architecture supports isolated, fast, reliable tests

## Phase 2: RED - Write Failing Tests

### 3. Write Unit Tests (Failing)
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Write FAILING unit tests for: $ARGUMENTS. Tests must fail initially. Include edge cases, error scenarios, and happy paths. DO NOT implement production code."
- Output: Failing unit tests, test documentation
- **CRITICAL**: Verify all tests fail with expected error messages

### 4. Verify Test Failure
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Verify that all tests for: $ARGUMENTS are failing correctly. Ensure failures are for the right reasons (missing implementation, not test errors). Confirm no false positives."
- Output: Test failure verification report
- **GATE**: Do not proceed until all tests fail appropriately

## Phase 3: GREEN - Make Tests Pass

### 5. Minimal Implementation
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Implement MINIMAL code to make tests pass for: $ARGUMENTS. Focus only on making tests green. Do not add extra features or optimizations. Keep it simple."
- Output: Minimal working implementation
- Constraint: No code beyond what's needed to pass tests

### 6. Verify Test Success
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Run all tests for: $ARGUMENTS and verify they pass. Check test coverage metrics. Ensure no tests were accidentally broken."
- Output: Test execution report, coverage metrics
- **GATE**: All tests must pass before proceeding

## Phase 4: REFACTOR - Improve Code Quality

### 7. Code Refactoring
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Refactor implementation for: $ARGUMENTS while keeping tests green. Apply SOLID principles, remove duplication, improve naming, and optimize performance. Run tests after each refactoring."
- Output: Refactored code, refactoring report
- Constraint: Tests must remain green throughout

### 8. Test Refactoring
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Refactor tests for: $ARGUMENTS. Remove test duplication, improve test names, extract common fixtures, and enhance test readability. Ensure tests still provide same coverage."
- Output: Refactored tests, improved test structure
- Validation: Coverage metrics unchanged or improved

## Phase 5: Integration and System Tests

### 9. Write Integration Tests (Failing First)
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Write FAILING integration tests for: $ARGUMENTS. Test component interactions, API contracts, and data flow. Tests must fail initially."
- Output: Failing integration tests
- Validation: Tests fail due to missing integration logic

### 10. Implement Integration
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Implement integration code for: $ARGUMENTS to make integration tests pass. Focus on component interaction and data flow."
- Output: Integration implementation
- Validation: All integration tests pass

## Phase 6: Continuous Improvement Cycle

### 11. Performance and Edge Case Tests
- Use Task tool with subagent_type="general-purpose"
- Prompt: "Add performance tests and additional edge case tests for: $ARGUMENTS. Include stress tests, boundary tests, and error recovery tests."
- Output: Extended test suite
- Metric: Increased test coverage and scenario coverage

### 12. Final Code Review
- Use Task tool with subagent_type="Plan"
- Prompt: "Perform comprehensive review of: $ARGUMENTS. Verify TDD process was followed, check code quality, test quality, and coverage. Suggest improvements."
- Output: Review report, improvement suggestions
- Action: Implement critical suggestions while maintaining green tests

## Incremental Development Mode

For test-by-test development:
1. Write ONE failing test
2. Make ONLY that test pass
3. Refactor if needed
4. Repeat for next test

Use this approach by adding `--incremental` flag to focus on one test at a time.

## Test Suite Mode

For comprehensive test suite development:
1. Write ALL tests for a feature/module (failing)
2. Implement code to pass ALL tests
3. Refactor entire module
4. Add integration tests

Use this approach by adding `--suite` flag for batch test development.

## Validation Checkpoints

### RED Phase Validation
- [ ] All tests written before implementation
- [ ] All tests fail with meaningful error messages
- [ ] Test failures are due to missing implementation
- [ ] No test passes accidentally

### GREEN Phase Validation
- [ ] All tests pass
- [ ] No extra code beyond test requirements
- [ ] Coverage meets minimum thresholds
- [ ] No test was modified to make it pass

### REFACTOR Phase Validation
- [ ] All tests still pass after refactoring
- [ ] Code complexity reduced
- [ ] Duplication eliminated
- [ ] Performance improved or maintained
- [ ] Test readability improved

## Coverage Reports

Generate coverage reports after each phase:
- Line coverage
- Branch coverage
- Function coverage
- Statement coverage

## Failure Recovery

If TDD discipline is broken:
1. **STOP** immediately
2. Identify which phase was violated
3. Rollback to last valid state
4. Resume from correct phase
5. Document lesson learned

## TDD Metrics Tracking

Track and report:
- Time in each phase (Red/Green/Refactor)
- Number of test-implementation cycles
- Coverage progression
- Refactoring frequency
- Defect escape rate

## Anti-Patterns to Avoid

- Writing implementation before tests
- Writing tests that already pass
- Skipping the refactor phase
- Writing multiple features without tests
- Modifying tests to make them pass
- Ignoring failing tests
- Writing tests after implementation

## Anti-Rationalization Table

These excuses signal you're about to break TDD discipline. Recognize them and return to the correct phase.

| Excuse | Rebuttal | Why It Matters |
|--------|----------|----------------|
| "I'll test after" | Tests written after implementation pass immediately, proving nothing. You can't verify a test catches bugs if you never saw it fail. | Tests-after are biased by implementation — you test what you built, not what's required |
| "This is too simple to test" | Simple code has the most unexamined assumptions. Simple code breaks at integration boundaries where you least expect it. | The simpler it seems, the more likely you'll miss an edge case |
| "TDD slows me down" | TDD prevents 2-3 hour debugging sessions. Writing a test takes minutes; debugging an untested bug takes hours. | The time you "save" skipping tests is borrowed against future debugging |
| "Just this once" | Every "just this once" becomes the new standard. Discipline has no exceptions — the exception IS the precedent. | One skip normalizes skipping. There is no "just this once" |
| "I already manually tested it" | Manual testing leaves no record, isn't repeatable, and doesn't catch regressions. It proves nothing to anyone but you, right now. | Manual tests evaporate. Automated tests compound |
| "Deleting my code is wasteful" | Sunk cost fallacy — keeping bad code costs more than writing it correctly. Code written without tests is unverified code. | Bad code costs more to maintain than to rewrite correctly |
| "The spirit matters, not the ritual" | The ritual IS the spirit — the specific order (test → fail → implement → pass → refactor) is what produces the quality guarantee. | Skipping steps while claiming to follow TDD is not following TDD |
| "I'll keep deleted code as reference" | Reference code biases you toward the wrong implementation. Start fresh — the test tells you what to write. | Prior code anchors you to assumptions that may be wrong |

## Success Criteria

- 100% of code written test-first
- All tests pass continuously
- Coverage exceeds thresholds
- Code complexity within limits
- Zero defects in covered code
- Clear test documentation
- Fast test execution (< 5 seconds for unit tests)

## Notes

- Enforce strict RED-GREEN-REFACTOR discipline
- Each phase must be completed before moving to next
- Tests are the specification
- If a test is hard to write, the design needs improvement
- Refactoring is NOT optional
- Keep test execution fast
- Tests should be independent and isolated

TDD implementation for: $ARGUMENTS

## Resources

- [Official Documentation](https://verified-skill.com/docs/reference/skills#tdd-cycle)
