Test-Driven Development Process

TDD is a design technique that uses tests as a tool. Design emerges from usage, not speculation. Short feedback loops let you course-correct immediately. The resulting architecture is testable by design, not retrofitted. We are not trying to rush towards a feature completion, it's important that the code is correct and well-designed, it's crucial to be thorough and only add what tests demand.

When starting, announce: "Using TDD skill in mode: [auto|human]"

MODE (user specifies, default: auto)

• auto: DO NOT ask for confirmation or approval. Proceed through all steps without stopping.
• human: wait for confirmation at key points

Core Rules

1. ALL code changes follow TDD - Feature requests mid-stream are NOT exceptions. Write test first, then code.
2. Write only one test at a time - focus on the simplest, lowest-hanging fruit test
3. Predict failures - State what we expect to fail before running tests
4. Two-step red phase:
   • First: Make it fail to compile (class/method doesn't exist)
   • Second: Make it compile but fail the assertion (return wrong value)
5. Minimal code to pass - Just enough to make the test green. If no test requires it, don't write it.
6. No comments in production code - Keep it clean unless specifically asked
7. Run all tests every time - Not just the one you're working on
8. Refactor at the first opportunity when the tests are green
9. Test behavior, not implementation - check responses or state, not method calls
10. Push back when something seems wrong or unclear

Boundary Testing (Layered Architectures)

For layered architectures, see boundary-testing.md for L3/L4 altitude testing, property-based tests with fast-check, behavioral assertions, HTTP contract tests, and architecture-specific anti-patterns.

Session Log

REQUIRED: Create tdd-session-log.md in the project root at the start of every TDD session. Append entries as events occur throughout the session. This is the first file written to disk — before any test comments or production code.

Entry format (one per line, append-only):

[PLAN] {description of test plan}
[RED-PREDICT] {test name} — expected failure: {reason}
[RED-CONFIRM] {test name} — actual failure: {actual error}
[GREEN] {test name} — passed with: {summary of code added}
[REFACTOR] {description of refactoring applied}

Test Planning

1. Think about what the code you want to write should do
2. Plan tests as single-line [TEST] comments — these are the FIRST artifact written to disk (before any production code). Each [TEST] comment MUST include a ZOMBIES letter annotation indicating which heuristic it covers:

   [TEST] Zero plus a number is equal to that number  <- Z
   [TEST] Add two positive numbers  <- O
   [TEST] Add many numbers in sequence  <- M
   [TEST] Adding MAX_INT overflows gracefully  <- B
   [TEST] Calculator exposes add() in public API  <- I
   [TEST] Division by zero throws ArithmeticError  <- E
   [TEST] Add returns a number  <- S

   Letters: Zero, One, Many, Boundary, Interface, Exception, Simple
3. Check completeness - walk through ZOMBIES explicitly:
   • Zero/empty cases covered?
   • One item cases covered?
   • Many items cases covered?
   • Boundary transitions covered?
   • Interface clarity verified?
   • Exceptions/errors covered? Verify every ZOMBIES letter appears at least once in the annotations. If any letter is missing, add a test for it.
4. Append a [PLAN] entry to tdd-session-log.md listing all planned tests
5. If MODE is human, wait for confirmation after test planning

Implementation Phase

1. Replace the next [TEST] comment directly with a failing test. No intermediate markers.
2. Test should be in format given-when-then (do not add as comments), with empty line separating them
3. Think through the expected value BEFORE writing the assertion. Trace the logic step by step.
4. Predict what will fail
5. Run tests, see compilation error (if testing something new)
6. Add minimal code to compile
7. Predict assertion failure
8. Run tests, see assertion failure
9. Add minimal code to pass
10. Predict whether the tests will pass and why. Run tests, see green
11. Simplify. For each line/expression you just added, ask: "Does a failing test require this?"
    • If no test requires it, delete it or if it's necessary, add a test comment to write that test
    • Run tests after each simplification
    • Repeat until every line is justified by a test
12. Refactor.
    • Reflect on the domain: Is there a missing concept that would make the code more expressive? An object waiting to be extracted? A better way to model the problem?
    • You may introduce domain concepts (new abstractions) as long as you add NO new behavior. Tests must still pass, and there should be no new code added that doesn't have tests.
    • Think about improvements to expressiveness, clarity, simplicity
    • Announce "Starting refactoring stage" and list planned refactorings
    • Implement one at a time, run tests after each
    • When done (or if none needed), say "Refactoring complete"
13. Go to step 1 for the next [TEST] comment. Repeat until all planned tests are passing.

Final Evaluation

1. Analyze the code written and think about the tests that we might have missed.
2. If there are any gaps in the tests, start the process for the missing tests from the beginning, starting from test comments then following the process flow until done
3. Is anything still hardcoded in the code that shouldn't be? Fix it, analyze test gaps and go back to previous stages if needed.
4. Analyze code expressiveness and quality. If there's anything you can see to improve, go to refactoring phase.