test-driven-development

name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code

Skill: test-driven-development

When

Implementing any feature, bugfix, or behavior change. No production code without a failing test first.

Note: This skill is typically invoked BY code-agent when new non-trivial behavior needs test-first implementation. Rarely loaded directly by orchestrators — prefer routing through code-agent which will invoke TDD as needed.

Flow

flowchart TD
    A[Write ONE failing test] --> B{Run test}
    B -->|Fails correctly| C[Write minimal code to pass]
    B -->|Wrong failure| A
    B -->|Passes immediately| D[Test is wrong — fix or delete]
    D --> A
    C --> E{Run test}
    E -->|Your tests pass| F[Refactor — keep green]
    E -->|Fails| C
    F --> G{More behavior needed?}
    G -->|Yes| A
    G -->|No| H[Done — your test files green, scoped VERIFY passes]

Iron Law

Code written before a test? Delete it. No "reference", no "adapting". Start fresh from tests.

RED — Write Failing Test

• One behavior per test, clear name, real code (no mocks unless unavoidable)
• Run: npm test -- path/to/test.test.ts — confirm fails for the right reason

GREEN — Minimal Code

• Simplest code to pass. Nothing beyond what the test requires.
• Run: re-run YOUR test file(s) (npm test -- path/to/test.test.ts) — confirm they pass, output pristine. Never the unscoped suite; the devil-advocate completion gate owns full-project verification.

REFACTOR — Clean Up

• Remove duplication, improve names, extract helpers
• Keep tests green. Don't add behavior.

Common Rationalizations

When Stuck

Red Flags — Delete and Start Over

Code before test, test passes immediately, can't explain why test failed, rationalizing "just this once".

See tdd-rationalizations-and-examples.md for expanded examples and rebuttals.