Test-Driven Development — Canon TDD

Rules

• Write tests FIRST. No implementation until RED is confirmed.
• NO NotImplementedError, NO pass, NO stubs, NO TODO.
• Tests must have concrete input/output assertions.
• One test at a time. Wait for confirmation before next.
• Tests must be behavioral (what it does), not structural (how it does it).
• Test must fail for the RIGHT reason — because the behavior doesn't exist yet, not because the module is missing.

Before Writing Any Test

1. List test scenarios from the requirements
2. Pick the smallest, most fundamental one first
3. Write exactly ONE test with:
   • Concrete input values
   • Concrete expected output
   • Clear assertion

Show the scenario list and explain your pick before writing.

RED → GREEN → REFACTOR

Phase	Action	Verify
RED	One failing test, concrete assertion	Exit code ≠ 0, fails for the right reason
GREEN	Simplest possible code (fake it if needed)	Exit code = 0, all tests pass
REFACTOR	Clean up, no behavior change	Exit code = 0, tests stay green

Stop after RED. Do not implement. Wait for user to confirm RED.

After GREEN, pick the next scenario. Repeat.

Tidy First

Separate structural from behavioral changes:

• Structural: rename, extract method, move code — no behavior change
• Behavioral: new functionality — always after structural
• Never mix the two in one commit

Commit Discipline

Each cycle gets separate commits:

test(<scope>): add failing test for <feature>     # RED
feat(<scope>): implement <feature> to pass tests   # GREEN
refactor(<scope>): clean up <feature>              # REFACTOR (optional)

With OpenSpec Tasks

1. Read current task from tasks.md
2. Extract scenarios (WHEN/THEN → concrete I/O list)
3. Canon TDD cycle per scenario
4. Mark task complete when all scenarios pass
5. Move to next task