TDD Cursor Rule Workflow for Context Engineering

tdd_workflow.mdc

---
alwaysApply: false
---
# TDD Workflow Rules

## Core TDD Principles
- **Always start with failing tests** before writing implementation code
- Follow the Red-Green-Refactor cycle strictly
- Write the minimal code necessary to make tests pass

## TDD Phase Transitions
When working on TDD iterations, emit a STATUS block to track progress:

```
<status>
    === TDD STATUS ===
    Phase: <current phase>
    (if phase is red) Did we see tests failing for the correct reason? Yes/No
    (if phase is green) Did we see tests passing correctly, proving the code is correct? Yes/No
    ==================
</status>
```

This status block is mandatory. It should be emitted again and again after each phase. The purpose of this is to keep track of our precise state, and to avoid proceeding from red to green if the tests are failing for the wrong reason, and to ensure that when tests pass it is for the correct reason and not for example due to a "skip" or similar.

## Red Phase Requirements
- Write a failing test that captures the desired behavior
- Verify the test fails for the **correct reason** (not due to syntax errors or missing dependencies)
- The failure should be specific to the missing functionality being implemented
- If we wrote a test and it passes without any changes to the code, it is useless and should be removed or fixed to fail for a correct reason.
- **CRITICAL**: If a test passes immediately without any code changes, STOP and analyze why
  - The test is likely not testing the specific new functionality
  - The test may be testing existing behavior or falling back to default cases
  - **Fix the test to fail for the correct reason** before proceeding
  - A passing test in RED phase without any code changes is a critical error and must be fixed before proceeding.
  ! [CRITICAL] A passing test in RED phase without any code changes is a critical error and must be fixed before proceeding. Never accept this, because this indicates that the test is useless and might as well be deleted !


## Green Phase Requirements
- Write the minimal implementation to make the test pass
- Verify tests pass and prove the code works correctly
- Do not add extra functionality beyond what the test requires

## Implementation Flow
1. **RED**: Write failing test → Run tests → Confirm failure for correct reason
2. **GREEN**: Write minimal implementation → Run tests → Confirm tests pass
3. **REFACTOR**: Improve code quality while keeping tests green (optional)
4. Repeat cycle for next feature/requirement

### Phases mandatory rules
* Prefer writing tests throughout the stack first, then implement all and proceed to green phase.
* In the rare case that you need to write an additional test, GO BACK to red phase for proper TDD workflow.

## How to plan a todo list for TDD
* Add a TODO step for each failing test required throughout the system
* Add a TODO step for explicitly validating that the test is failing
* Add a TODO step to ensure that we never ever proceed to green phase without a failing test, no matter what
* Add a TODO step for writing minimal implementation to make the test pass
* Add a TODO step for explicitly validating that the tests pass
* Add a TODO step for ensuring 100% coverage
* Add a TODO step for refactoring if needed for improving quality

## Test Quality Standards
- Tests must be specific and focused on single behaviors
- Test names must clearly describe what is being tested
- Assertions must be clear and meaningful
- Tests must be independent and repeatable

## Handling bugs
- A bug existing in the code first and foremost indicates that the tests are incorrect or incomplete
- First add a failing test for the bug
- Only then fix the code

## Coverage
- Always go for 100% coverage
- When writing tests, consider all branches and functions and edge cases
- When removing functionality, check coverage to see if we now have 'dead code' that can be removed

Good!