Sub-Skill: Test-Driven Development

---
description: Apply when adding new behavior or fixing a bug. Red-green-refactor cycle, test-first discipline, when TDD doesn't pay.
alwaysApply: false
---

# Sub-Skill: Test-Driven Development

**Purpose:** Prevents the common failure mode where agents write implementation first and tests second — producing tests that validate the code as-written rather than the intended behavior.

## Rules

### The Red-Green-Refactor Cycle

1. **MUST: Always write a failing test before writing production code.** The test defines the desired behavior. If you cannot articulate a failing test, you do not yet understand the requirement. Reference: ERR-2026-017.

2. **MUST: Never write more production code than necessary to pass the current failing test.** Resist the urge to implement the full feature. One test, one behavior, one pass. Then refactor.

3. **SHOULD: After each green test, look for refactoring opportunities before writing the next test.** Refactoring under green tests is safe. Refactoring without tests is gambling.

4. **AVOID: Writing multiple tests at once before making any pass.** One failing test at a time keeps feedback loops tight and prevents losing track of which behavior you are implementing.

### Test Design

5. **SHOULD: Name tests to describe the scenario and expected outcome, not the function under test.** `test_empty_cart_returns_zero_total` not `test_calculate_total`. The name is documentation.

6. **MUST: Ensure each test is independent and can run in any order.** Shared mutable state between tests causes flaky suites. Use setup/teardown or fresh fixtures per test.

7. **SHOULD: Test behavior, not implementation.** Assert on outputs and observable side effects, not internal method calls. Implementation-coupled tests break on every refactor.

8. **AVOID: Testing private methods directly.** Test through the public API. If a private method needs its own tests, it probably belongs in a separate module.

### Coverage and Boundaries

9. **SHOULD: Cover the happy path, at least one edge case, and at least one error case per public function.** Three tests minimum per meaningful behavior.

10. **AVOID: Chasing 100% line coverage as a goal.** Coverage measures execution, not correctness. A test that executes code without asserting anything is worthless. Aim for high branch coverage on business logic.

11. **SHOULD: Use test doubles (mocks, stubs, fakes) only at architectural boundaries.** Mock the database, the network, the file system — not your own classes. Over-mocking makes tests brittle and meaningless.

### When NOT to TDD

12. **AVOID: TDD for exploratory prototypes and throwaway spikes.** When you do not yet know what the interface should be, experimentation is more valuable than premature tests. Delete the spike afterward.

13. **SHOULD: Use TDD for bug fixes — always.** Write a test that reproduces the bug first. Green means the bug is fixed. This prevents regressions permanently.

14. **AVOID: TDD for pure configuration, static markup, or generated code.** If there is no branching logic, there is nothing meaningful to test-drive.

### Discipline

15. **MUST: Never commit code where all tests pass but you skipped the red step.** If you wrote production code first and tests second, those tests may not actually exercise the new behavior. Rewrite them.

## See also

- `skills/code-quality/SKILL.md` — General quality rules including testing conventions
- `skills/python/SKILL.md` — Python-specific pytest patterns (rules 16–23)

## Why This Sub-Skill Earns Stars

LLM agents almost universally write code first and tests second — or skip tests entirely. This produces tests that validate the implementation rather than the specification, meaning bugs in the implementation are "verified" by the test. The red-green-refactor discipline catches this: if you never saw the test fail, you cannot trust that it tests anything real.