---
name: run-tdd
description: Write failing unit tests (RED), implement minimal code (GREEN), refactor with quality validation for Stages F-H of the VibeFlow docs-first workflow
metadata:
  triggers:
    - implement feature
    - start TDD
    - write tests
    - Stage F
    - Stage G
    - Stage H
    - RED phase
    - GREEN phase
    - REFACTOR phase
---

# run-tdd

TDD implementation cycle for Stages F-H of the VibeFlow docs-first workflow.

## Purpose

This skill guides the TDD cycle:
- **Stage F (RED)**: Create stubs + write failing unit tests
- **Stage G (GREEN)**: Implement minimal code to pass tests
- **Stage H (REFACTOR)**: Write integration tests + refactor + quality validation

## Workflow

```
Stage F: RED
    │
    ├── Create stubs from Feature Spec API Design
    ├── Write failing unit tests
    ├── Tests fail with NotImplementedError
    └── Checkpoint #3: Tests Complete
    │
    ▼
Stage G: GREEN
    │
    ├── Implement minimal code to pass tests
    ├── If contracts change → Stage G.1
    └── All unit tests pass
    │
    ▼
Stage H: REFACTOR
    │
    ├── Write integration tests for I/O
    ├── Pass integration tests
    ├── Refactor with tests green
    ├── Complete H.4 quality validation
    └── Checkpoint #4: Implementation Complete
```

## Usage

### Start TDD Cycle

```
/run-tdd start
```

Guides through the full TDD cycle starting with Stage F.

### Stage F: RED Phase

```
/run-tdd red
```

1. Create implementation stubs from Feature Spec API Design
2. Write failing unit tests
3. Verify tests fail with "not implemented" errors

### Stage G: GREEN Phase

```
/run-tdd green
```

1. Implement minimal code to pass unit tests
2. Check for contract changes (trigger G.1 if needed)
3. Verify all unit tests pass

### Stage H: REFACTOR Phase

```
/run-tdd refactor
```

1. Write integration tests for I/O boundaries
2. Refactor code while keeping tests green
3. Complete H.4 quality validation

### Validate Tests

```
/run-tdd validate
```

Runs test quality validation (Stage H.4 checklist).

### Handle Design Changes

```
/run-tdd g1
```

Guides through Stage G.1 protocol when implementation reveals contract changes.

## Stage G.1: Design Changes Protocol

If implementation reveals contract changes, **STOP IMMEDIATELY** and follow these steps:

1. Document the discovered issue
2. Update SPEC first (increment version)
3. Create/update ADR if non-trivial
4. Update Feature Spec API Design
5. Update tests to new contract
6. Resume implementation

**Contract changes that trigger G.1:**
- API/Interface signature changes
- Database schema changes
- Event format changes
- New external dependencies
- SLO changes

**Changes that DON'T trigger G.1:**
- Internal algorithms
- Private function names
- Error handling improvements (within taxonomy)
- Performance optimizations (within SLO)

## Test Categorization

All tests must have categorization tags:

**Speed/Scope (required):**
- `unit` / `fast` — All dependencies mocked, runs in ms
- `integration` / `medium` — Uses test DB, mocked external APIs
- `e2e` / `slow` — Full workflow, multiple components
- `real_api` — Makes real external API calls

**Module (required):**
- Tag with module name (e.g., `accounts`, `generation`, `api`)

## Stage H.4 Quality Validation

Before completing Stage H, validate:

**Organization:**
- File structure follows conventions
- Test names use `test_<what>_<condition>_<expected>`
- Related tests grouped

**Usefulness:**
- Tests based on acceptance criteria
- Happy path, edge cases, error cases tested
- Tests validate behavior, not implementation

**Code Quality:**
- External dependencies mocked in unit tests
- AAA pattern clear
- No skipped tests without justification

**Categorization:**
- All tests have speed/scope tags
- No real API calls in "unit" tests

**Reliability:**
- Unit tests < 1s each
- Integration tests < 5s each
- Tests pass consistently (no flaky tests)

**Quality Gate:**
- 0-2 violations: PASS
- 3-5 violations: CONDITIONAL
- 6+ violations OR 2+ major: FAIL

## Validation

- `scripts/validate_red.py` — Validate Stage F (tests failing correctly)
- `scripts/validate_green.py` — Validate Stage G (tests passing)
- `scripts/validate_refactor.py` — Validate Stage H (integration + quality)
- `scripts/check_coverage.py` — Report test coverage

## References

See `references/`:
- `tdd-policy.md` — TDD policy and requirements
- `tdd-guide.md` — TDD workflow guidance
- `stage-g1-protocol.md` — Design change handling protocol

## Manifest Update

After completing each stage, update `docs/workflow-state.yaml`:

**Stage F (RED):**
- Set `stage: F`

**Checkpoint #3 (after Stage F):**
- Set `checkpoint: 3` after passing validation
- Criteria: Stubs exist matching Feature Spec API Design, unit tests exist and fail with NotImplementedError

**Stage G (GREEN):**
- Set `stage: G`

**Stage H (REFACTOR):**
- Set `stage: H`

**Checkpoint #4 (after Stage H):**
- Set `checkpoint: 4` after passing validation
- Criteria: All unit tests pass, integration tests pass, H.4 quality validation passes

## Git Commit

After completing each stage, ask the user for permission before committing:

**Stage F (RED):**
```bash
git add <test-files> <stub-files> docs/workflow-state.yaml
git commit -m "feat(<module>): add failing tests and stubs (#ft-<ID>)"
```

**Stage G (GREEN):**
```bash
git add <source-files> docs/workflow-state.yaml
git commit -m "feat(<module>): implement to pass tests (#ft-<ID>)"
```

**Stage H (REFACTOR):**
```bash
git add <source-files> <test-files> docs/workflow-state.yaml
git commit -m "feat(<module>): add integration tests and refactor (#ft-<ID>)"
```

Replace `<module>` with the actual module name, `<ID>` with the work item ID, and file placeholders with actual paths.

## Auto-Advance

After each sub-stage commit, directly run `/manage-work advance <ID>`:
1. **After Stage F (RED) commit** → advances F→G. The advance command will automatically validate Checkpoint #3 at the F→G boundary.
2. **After Stage G (GREEN) commit** → advances G→H.
3. **After Stage H (REFACTOR) commit** → advances H→DONE or I. The advance command will automatically validate Checkpoint #4 at the H→DONE/I boundary.