## TDD Fundamentals

### The TDD Cycle

The foundation of TDD is the Red-Green-Refactor cycle:

1. **Red Phase**: Write ONE failing test that describes desired behavior
   - The test must fail for the RIGHT reason (not syntax/import errors)
   - Only one test at a time — this is critical for TDD discipline
   - **Adding a single test to a test file is ALWAYS allowed** — no prior test output needed
   - Starting TDD for a new feature is always valid, even if test output shows unrelated work

2. **Green Phase**: Write MINIMAL code to make the test pass
   - Implement only what’s needed for the current failing test
   - No anticipatory coding or extra features
   - Address the specific failure message
   - All changes required to make a failing test pass (imports, routing, function body, etc.) constitute ONE atomic step — do not demand they be split into artificial sub-steps

3. **Refactor Phase**: Improve code structure while keeping tests green
   - Only allowed when relevant tests are passing
   - Requires proof that tests have been run and are green
   - Applies to BOTH implementation and test code
   - No refactoring with failing tests — fix them first

### Core Violations

1. **Multiple Test Addition**
   - Adding more than one new test at once
   - Exception: Initial test file setup or extracting shared test utilities

2. **Over-Implementation**
   - Adding public functions, methods, or classes that no existing failing test exercises
   - Adding entirely new features unrelated to the current failing test
   - Internal helpers, routing logic, imports, and private functions that serve the current failing test are NOT over-implementation

3. **Premature Implementation**
   - Adding implementation before a test exists and fails properly
   - Adding implementation without running the test first
   - Refactoring when tests haven’t been run or are failing

### Critical Principle: Advancing the Test

The goal of each Green phase step is to advance the failing test toward passing. Use this objective test to judge a change:

- If removing the change would leave the test failure UNCHANGED → the change is unnecessary, block it
- If removing the change would cause the test to regress to an earlier failure (e.g., from assertion error back to import/attribute error) or prevent it from passing → the change is necessary, allow it

### General Information

- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
- In the refactor phase, it is perfectly fine to refactor both test and implementation code. That said, completely new functionality is not allowed. Types, clean up, abstractions, and helpers are allowed as long as they do not introduce new behavior.
- Adding types, interfaces, or a constant in order to replace magic values is perfectly fine during refactoring.
- Provide the agent with helpful directions so that they do not get stuck when blocking them.
