tdd-red-green-refactor

TDD: red / green / refactor / simplify

The four phases (per task)

1. RED — write a failing test

• Read the task entry in 04-tasks.md. Confirm Test-IDs and AC-IDs.

• Write the smallest possible test that asserts the behavior described by the AC.

  • Annotation block on every @Test method is non-negotiable: @Test → @Tag("AC-NNN") → @DisplayName("..."). Write the @DisplayName before the test body — the act of articulating the display name forces clarity about what the test verifies. Format for AC-traced tests: "<T-ID>: given <precondition>, when <action>, then <outcome>". Short BDD-style sentence is acceptable for utility/regression tests not tied to a specific AC. (Project rule: feedback_displayname_on_every_test.md.)

• Run only that test (mvn -Dtest=ClassName#method test).

• The test must fail, and the failure must be for the right reason (the asserted behavior is missing, not a typo or compilation error).

• Append a red block to 05-implementation-log.md with the failing command and the first 10 lines of the failure output.

• Update .specs/<id>/.tdd-state.json:

  { "active_task": "T-001", "tasks": { "T-001": { "phase": "red", "red_at": "2026-04-18T10:00:00Z", "red_test_signature": "...", "red_failure_excerpt": "..." } } }
  

The block-impl-without-failing-test hook reads this file. No src/main/** edit is allowed unless phase == red and red_failure_excerpt is non-empty.

2. GREEN — minimum production code

• Edit only files in the task's Files in scope. The hook enforces this.
• Write the minimum code to make the failing test pass. No speculative features. No "while I'm here" cleanups.
• Re-run the test (mvn -Dtest=...). It must pass.
• Run the module's full Surefire suite to ensure no regression (mvn -q test -pl <module>).
• Append a green block to 05-implementation-log.md.
• Set .tdd-state.json phase to green.

3. REFACTOR — improve internals, hold behavior