Test-Driven Development

Before You Start

Select the blueprint

1. If the user named a blueprint file, use that file.
2. Otherwise ask the user which blueprint to use, listing what is in docs/plans/. Never guess — /tdd takes exactly one blueprint.
3. If no blueprint exists in docs/plans/, tell the user — recommend running /blueprint first, or if they prefer, proceed by driving RED→GREEN directly from their description.

Slice completion checkboxes

• Pick the first slice whose TDD done checkbox is unchecked.
• When every Acceptance Criterion in the slice is green and refactored, tick its TDD done checkbox in the blueprint, then move to the next slice.
• No in-progress marker is maintained. After an interruption, resume at the first unchecked slice and re-run its existing tests before continuing.
• Slices with Blocked by: None may be run in parallel at the agent's discretion; keep one RED→GREEN→REFACTOR cycle per slice and tick each checkbox independently.
• When reading domain terminology, if CONTEXT-MAP.md exists, read it and read each context relevant to the topic; if unclear which context applies, ask the user.

Non-Negotiable Gate

You must witness a test fail for the expected reason before writing any implementation code.

If you find yourself writing implementation without a preceding failing test:

1. STOP immediately.
2. Delete the implementation code you just wrote.
3. Write the test first.
4. Watch it fail.
5. Only then write the implementation again.

This is not advice. This is the rule.

Philosophy

Core principle: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.

Good tests are integration-style: they exercise real code paths through public APIs. They describe what the system does, not how it does it. They survive refactors because they don't care about internal structure.

Bad tests are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means. The warning sign: your test breaks when you refactor, but behavior hasn't changed.

See tests.md for examples and mocking.md for mocking guidelines.

Anti-Pattern: Horizontal Slices

DO NOT write all tests first, then all implementation. This is "horizontal slicing."

WRONG (horizontal):
  RED:   test1, test2, test3, test4
  GREEN: impl1, impl2, impl3, impl4

RIGHT (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3
  ...

Workflow

1. RED — Write a Failing Test

Write ONE test for ONE behaviour from the current slice's Acceptance Criteria.

MANDATORY VERIFICATION:

1. Run the test immediately.
2. It must fail.
3. The failure must be because the behaviour is missing — NOT a syntax error, NOT a test setup problem.
4. If it passes immediately → the behaviour already exists, rewrite the test.
5. If it fails with syntax/import errors → fix those, re-run, re-verify.

Do not write implementation code until you have witnessed the test fail for the right reason.

2. GREEN — Minimal Code to Pass

Read docs/house-style.md if it exists, then write the minimal code to make this single test pass.

• No extra features.
• No "I'll need this later."
• No anticipating the next test.

VERIFY: Run the test. It must pass. Run all existing tests — they must also pass.

3. REFACTOR — Clean Up

After the test is green, look for refactor opportunities:

• Duplication → Extract function/class
• Long methods → Break into private helpers (keep tests on public interface)
• Shallow modules → Combine or deepen — see /codebase-design for the deletion test, depth assessment, and seam discipline
• Feature envy → Move logic to where data lives
• Primitive obsession → Introduce value objects
• Improve names
• Existing code the new code reveals as problematic
• Run tests after each refactor step

Never refactor while RED. Get to GREEN first.

4. Next Behaviour

Return to RED for the next behaviour within this slice. When all Acceptance Criteria for the slice are green and refactored, tick the slice's TDD done checkbox in the blueprint, then move to the next slice.

Checklist Per Cycle

[ ] RED witnessed — test failed for the expected reason before implementation
[ ] Test describes behaviour, not implementation
[ ] Test uses public interface only
[ ] Code is minimal for this test — no speculative additions
[ ] All existing tests still pass

Handoff

When all slices are complete and the full test suite passes, verify every TDD done checkbox in the blueprint is ticked, then tell the user:

"TDD complete for docs/plans/{filename}. All module tests pass. Ready for /integrate — run it without a filename to verify this blueprint."