/test-driven-development

name: test-driven-development
user-invocable: false
description: "RED-GREEN-REFACTOR cycle with strict phase gates for TDD."
success-criteria:
  - "Failing test written before implementation code"
  - "All new tests pass after implementation"
  - "No pre-existing tests broken"
  - "Refactor phase completed without changing test outcomes"
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
routing:
  triggers:
    - "TDD"
    - "test first"
    - "red green refactor"
    - "write tests first"
    - "test-driven"
    - "start with failing test"
    - "tests before code"
  category: testing
  pairs_with:
    - verification-before-completion
    - testing-preferred-patterns
    - vitest-runner

Test-Driven Development (TDD) Skill

Enforce the RED-GREEN-REFACTOR cycle for all code changes. Tests are written before implementation code, verified to fail for the right reasons, and maintained through disciplined development cycles.

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. | | full RED-GREEN-REFACTOR walkthroughs in Go, Python, JavaScript | `examples.md` | Loads detailed guidance from `examples.md`. | | detailed phase steps, rationale, or language-specific test commands | `phase-guidance.md` | Loads detailed guidance from `phase-guidance.md`. |

Instructions

Before starting any TDD cycle, read and follow repository CLAUDE.md files. Project instructions override default TDD behaviors because local conventions (test frameworks, directory layout, naming) vary across codebases.

Full phase guidance (steps, rationale, code examples, language commands) lives in [references/phase-guidance.md](references/phase-guidance.md). Load it when you need detailed instructions or examples. The sections below are the lean phase skeleton plus the mandatory gates.

Phase 1: Write a Failing Test (RED)

Write a test that describes the desired behavior before any implementation exists. Use specific assertions, descriptive names, Arrange-Act-Assert pattern, and one concept per test. Run the test and show full output. Details: [references/phase-guidance.md](references/phase-guidance.md).

RED Phase Gate

Proceed to the GREEN phase only after all of these are true:

• [ ] Test file is created and saved
• [ ] Test has been executed
• [ ] Test output shows FAILURE (not syntax/import error)
• [ ] Failure message indicates missing implementation

Phase 2: Verify Failure Reason (RED Verification)

The test must fail because the feature is not implemented, NOT because of syntax errors, import errors, wrong test setup, or unrelated failures. Expected patterns per language and recovery steps: [references/phase-guidance.md](references/phase-guidance.md).

Phase 3: Implement Minimum Code (GREEN)

Write ONLY enough code to make the failing test pass. No extra features. Hardcoded values are OK initially. Over-engineering and correct examples: [references/phase-guidance.md](references/phase-guidance.md).

Phase 4: Verify Test Passes (GREEN Verification)

Run the test and the full suite; show complete output. Never summarize. Debug guidance: [references/phase-guidance.md](references/phase-guidance.md).

GREEN Phase Gate

Proceed to the REFACTOR phase only after all of these are true:

• [ ] Implementation code is written
• [ ] New test has been executed and shows PASS
• [ ] Full test suite has been executed
• [ ] No other tests have been broken

Phase 5: Refactor (REFACTOR)

Improve code quality without changing behavior. Establish a green baseline first, refactor incrementally, run tests after every step. Test behavior, not internals. Decision criteria table and behavior-vs-internals examples: [references/phase-guidance.md](references/phase-guidance.md).

REFACTOR Phase Gate

Mark the task complete only after all of these are true:

• [ ] All refactoring changes are saved
• [ ] Full test suite has been executed
• [ ] ALL tests pass (not just the new one)
• [ ] Code quality has been evaluated against the criteria table above

Phase 6: Commit

Commit the test and implementation together as an atomic unit. Run the full suite, commit with a descriptive message, clean up temporary files. Report facts without self-congratulation.

Cycle Discipline

Each feature gets its own RED-GREEN-REFACTOR cycle. Do not batch multiple features into one cycle. Wrong-vs-correct cycle examples: [references/phase-guidance.md](references/phase-guidance.md).

Reference Material

• [references/phase-guidance.md](references/phase-guidance.md) — Full phase steps, rationale, code examples, Arrange-Act-Assert, optional techniques, language-specific testing commands
• [references/error-handling.md](references/error-handling.md) — Symptoms, causes, and solutions for stuck cycles (passes too early, wrong failure reason, green-but-broken, refactor breakage)
• [references/examples.md](references/examples.md) — Language-specific TDD examples (Go, Python, JavaScript)

Error Handling

Load [references/error-handling.md](references/error-handling.md) when a cycle is stuck. It covers: test passes before implementation, test fails for wrong reason, tests pass but feature does not work, refactoring breaks tests.