| name | running-tdd-cycles |
| description | Drive strict red-green-refactor TDD discipline on any code change, any language. |
| allowed-tools | Read, Edit, Write, Grep, Glob, Bash(pytest *), Bash(uv run pytest *), Bash(npm test *), Bash(npm run test *), Bash(npx vitest *), Bash(npx jest *), Bash(go test *), Bash(cargo test *), Bash(rspec *), Bash(mvn test *), Bash(gradle test *), Bash(forge test *), Bash(forge coverage *), Bash(git status *), Bash(git diff *), Bash(git add *), Bash(git commit *) |
Loop
For each new piece of behaviour:
1. Extract <requirement> — the smallest piece of logic that adds value.
2. RED → write ONE failing test that pins down <requirement>.
3. GREEN → write the minimal code that makes it pass.
4. REFACTOR → improve structure with the test as a safety net.
5. COMMIT → one logical change per commit (defer to committing-changes).
6. Repeat 2–5 until the task is done.
7. REVIEW → defer to reviewing-changes for the final pass.
Always one requirement per cycle. If the cycle feels big, the requirement was too big — split it.
RED — write a failing test
- One test, one requirement. Don't write a test suite up front; one test, fail, pass, refactor, next.
- Test names are claims, not labels. Verify the fixture shape, input source, and assertion target match the name before the test goes green. A test named
test_decodesV4Quote that loads a V5 fixture is silently broken: it passes but pins the wrong invariant, and the regression lands in the wrong place. Common causes: renamed a test and forgot to update the fixture; copy-pasted a fuzzy assertion from a sibling test without re-targeting it.
- Arrange-Act-Assert. Three blocks, one assertion focus. Use
should_X_when_Y naming where the framework allows it.
- Fail for the right reason. Run the test before writing implementation. The failure message must point at missing behaviour, not at a typo, missing import, or fixture mistake. If it doesn't, the test is wrong.
- No premature edge cases. Cover the happy path first. Edge cases (
null, empty collections, boundary values, concurrent access, errors) get their own RED-GREEN-REFACTOR cycles.
- Property-based when applicable. Prefer
hypothesis (Python), fast-check (JS/TS), or quickcheck (Haskell/Rust) for invariants. Example-based tests are for specific edge cases or documentation. See reference/property-based-testing.md.
- Reuse strategies. Before writing a generator, check
tests/strategies.py (or the project equivalent) for shared fixtures/strategies. Add new ones back to the shared module.
Framework cues
- Python (pytest) — fixtures with explicit scopes,
pytest.mark.parametrize for multiple cases, hypothesis for properties.
- JS/TS (Vitest/Jest) —
vi.fn() / jest.fn() mocks; @testing-library/* for components; fast-check for properties.
- Go — table-driven tests with subtests via
t.Run(name, func(t *testing.T) {...}); t.Parallel() where safe.
- Ruby (RSpec) —
let for lazy fixtures, let! for eager; nested context for branching scenarios.
- Solidity (Foundry) —
forge test -vvv; parametric fuzz tests via function testFoo(uint256 x); bound(x, min, max) not if-guards. See solidity-conventions.
GREEN — minimal code to pass
- Smallest possible change. Hard-coded returns are fine for the first cycle. Triangulate (generalise) only when a second test forces it.
- No bonus features. Don't add error handling, logging, optimisation, or generality unless a test demands it. The next cycle will.
- Don't modify the test. If the test is wrong, go back to RED. If the test is right and the implementation is wrong, fix the implementation.
- Run the full test suite after each change. Confirm green; confirm no regression.
REFACTOR — improve structure
- Tests stay green throughout. Run the suite after every micro-step.
- Code smells to act on: duplication (extract method/class), long methods (decompose), large classes (split SRP), long parameter lists (parameter object), feature envy (move method), primitive obsession (value object), switch statements driven by type (polymorphism), dead code (delete).
- SOLID weights. Single Responsibility first; the others when they pull their weight. See engineering-philosophy.
- Tests refactor too. Extract common fixtures, rename for clarity, eliminate test duplication. Coverage stays equal or improves.
- Performance refactors are measured. Profile before, profile after; commit the measurement alongside the change.
- Refactoring is not optional. If you skip it, technical debt compounds and the next RED gets harder to write.
Anti-patterns
- Writing implementation before the test.
- Writing a test that already passes.
- Writing many tests at once and implementing them in a batch.
- Modifying a test to make it pass.
- Skipping refactor because "the test passed."
- Adding tests during the GREEN phase.
- Test-after rationalised as TDD.
If the discipline breaks: stop, identify the violated phase, revert to the last green state, resume from the right phase, note what went wrong.
Validation checkpoints
End of RED: test exists, test fails, failure message names the missing behaviour, no false positive.
End of GREEN: all tests pass, the change is the minimum that could possibly work, the test wasn't modified, coverage didn't drop.
End of REFACTOR: all tests still pass, complexity (cyclomatic, length) at least no worse, duplication addressed, names readable, performance measured if performance was the goal.
Scratch testing
Quick exploration belongs in a gitignored scratch file, not in production code or in the test suite:
- Python →
test.py (see python-conventions and reference/scratch-testing.md).
- Go →
test.go with //go:build scratch tag (see go-conventions).
- Solidity →
script/Scratch.s.sol or chisel REPL (see solidity-conventions).
Never use inline heredocs (uv run python << EOF, go run -, forge script --via-stdin) — the file pattern keeps history and stays inspectable.
Cross-references
committing-changes — commit after every successful GREEN or REFACTOR phase.reviewing-changes — final pass after the loop ends.python-conventions / go-conventions / solidity-conventions — language-specific test runner setup.engineering-philosophy — Small Steps, Investigate-Don't-Mask, KISS, YAGNI all apply directly.
Reference
