tdd

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

STARTER_CHARACTER = 🔴 for red test, 🌱 for green, 🌀 when refactoring, always followed by a space

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:
5. First: Make it fail to compile (class/method doesn't exist)
6. Second: Make it compile but fail the assertion (return wrong value)
7. Minimal code to pass - Just enough to make the test green. If no test requires it, don't write it.
8. No comments in production code - Keep it clean unless specifically asked
9. Run all tests every time - Not just the one you're working on
10. Refactor at the first opportunity when the tests are green
11. Test behavior, not implementation - check responses or state, not method calls
12. Push back when something seems wrong or unclear

Test Planning

1. Think about what the code you want to write should do
2. Plan tests as single-line [TEST] comments. Example: ``` [TEST] Zero plus a number is equal to that number [TEST] Add two positive numbers [TEST] Add two negative numbers [TEST] Adds a negative and a positive number [TEST] Division by zero is not allowed ... ```
3. Check completeness - walk through [ZOMBIES](references/zombies.md) explicitly:
4. Zero/empty cases covered?
5. One item cases covered?
6. Many items cases covered?
7. Boundary transitions covered?
8. Interface clarity verified?
9. Exceptions/errors covered?
10. 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 — empty method bodies, placeholder returns, missing classes. Do not implement logic yet.
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. If the test passed without ever being red, pause. Identify which earlier step added the code this test is exercising for free. Call it out (e.g., "This passed immediately because I added X at step N before a test required it"). Tighten discipline on remaining tests.
12. Simplify. For each line/expression you just added, ask: "Does a failing test require this?"
13. If no test requires it, delete it or if it's necessary, add a test comment to write that test
14. Run tests after each simplification
15. Repeat until every line is justified by a test
16. Refactor.
17. 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?
18. 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.
19. Think about improvements to expressiveness, clarity, simplicity
20. Say 🧹 Starting refactoring stage and list planned refactorings
21. Implement one at a time, run tests after each
22. When done (or if none needed), say "🧹 Refactoring complete"
23. 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.