Test-Driven Development workflow specialist using RED-GREEN-REFACTOR cycle for test-first software development. Use when developing new features from scratch or when behavior specification drives implementation.
Test-Driven Development workflow specialist using RED-GREEN-REFACTOR cycle for test-first software development. Use when developing new features from scratch or when behavior specification drives implementation.
when_to_use
Use for Test-Driven Development: the RED-GREEN-REFACTOR cycle for test-first software development, new-feature implementation from scratch, and behavior-specification-driven implementation.
Understandability: Tests serve as living documentation
Security: Security tests written before implementation
Transparency: Test failures provide immediate feedback
Integration Points
With DDD Workflow
TDD and DDD are complementary:
TDD for new code
DDD for existing code refactoring
Hybrid mode combines both approaches
With Testing Workflow
TDD integrates with testing workflow:
Uses specification tests
Integrates with coverage tools
Supports mutation testing for test quality
With Quality Framework
TDD outputs feed into quality assessment:
Coverage metrics tracked
TRUST 5 validation for changes
Quality gates enforce standards
Troubleshooting
Common Issues
Test is Too Complex:
Break into smaller, focused tests
Test one behavior at a time
Use test fixtures for complex setup
Implementation Grows Too Fast:
Resist urge to implement untested features
Return to RED phase for new functionality
Keep GREEN phase minimal
Refactoring Breaks Tests:
Revert immediately
Refactor in smaller steps
Ensure tests verify behavior, not implementation
Recovery Procedures
When TDD discipline breaks down:
Stop and assess current state
Write characterization tests for existing code
Resume TDD for remaining features
Consider switching to Hybrid mode
Version: 1.0.0
Status: Active
Common Rationalizations
Rationalization
Reality
"I'll add tests after the implementation works"
Post-hoc tests verify what the code does, not what it should do. They miss the bugs RED phase catches.
"The existing tests cover this case"
Existing tests verify old behavior. New behavior needs its own failing test first.
"This function is too simple to test"
Simple functions accumulate complexity. The test documents expected behavior before drift.
"I tested it manually in the terminal"
Manual checks do not persist. Tomorrow's change breaks the contract with no signal.
"The test requires complex mocking"
If the test is hard to write, the code is hard to reason about. Refactor the design first.
"Tests slow me down"
Test-first surfaces design problems early, when they are cheapest to fix.
"I'll skip REFACTOR this cycle to keep moving"
Skipped refactors compound. The next cycle starts from a worse baseline.
DAMP over DRY: In test code, prefer Descriptive And Meaningful Phrases over Don't Repeat Yourself. Duplication inside a test that makes the intent obvious is better than an abstraction that hides it.
Beyonce Rule: If you liked it, you should have put a test on it. Any behavior CI does not verify will eventually break without warning.
Red Flags
Implementation file created in the same commit as its test file (RED phase skipped)
Test names describe implementation (test_function_returns_true) instead of behavior (test_user_login_rejects_expired_token)
All tests in a new file pass on first run — no RED phase was captured
Commit message says "add tests" after the feature is already merged
Test suite contains mocks of the code under test (mocking implementation, not collaborators)
Coverage dropped in the commit that added a new feature
Verification
Git history shows a failing-test commit before the implementation commit, or evidence of RED in the same commit
Test names read as behavior specifications, not function descriptions
Every new public function has at least one corresponding test case
Full test suite passes (paste command output)
Coverage for changed files is measured and reported (show tool output)
No skip, xit, or disabled tests were added in this change
REFACTOR phase was executed or explicitly justified as unnecessary
Test-First Anti-Cheat
[ZONE:Evolvable] [HARD] The Red Flags and Verification checklists above sit in advisory (evolvable) blocks and are consumed by no completion gate. This section promotes them into two enforced invariants that make test-first falsifiable in the completion matrix.
Invariant i — RED failure output is mandatory completion evidence. The verbatim RED failing-test output (the failing-test run captured BEFORE any implementation makes it pass) MUST be observed and shown as part of run-phase completion evidence. A run that cannot produce this output skipped RED and cannot be reported as clean.
Invariant ii — implementation written before its failing test is deleted and re-derived test-first. Any implementation code written before its failing test exists MUST be deleted and re-derived from a failing test (RED then GREEN). "I already wrote the implementation, so the test passes on first run" is the exact failure mode this invariant forbids — it is test-after, not test-first, and it leaves no RED output (Invariant i) to show as evidence.
These two invariants close the falsifiability gap: before them, a fully-passing self-verification matrix was producible with NO RED evidence, so test-first could not be distinguished from test-after by the completion report. After them, the matrix requires the verbatim pre-GREEN RED output, so a run that skipped RED has no such output to supply and the matrix is structurally incomplete.
