Use when implementing any feature or bugfix, before writing implementation code. This skill now also owns the broader verification workflow that was previously split into `testing-protocol`.
Write the test first. Watch it fail. Write minimal code to pass.
The preserved browser-verification and broader test-checklist material from testing-protocol now lives under merged/testing-protocol/.
Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
Violating the letter of the rules is violating the spirit of the rules.
Always:
Exceptions (ask your human partner):
Thinking "skip TDD just this once"? Stop. That's rationalization.
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
Write code before the test? Delete it. Start over.
No exceptions:
Implement fresh from tests. Period.
digraph tdd_cycle {
rankdir=LR;
red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
verify_red [label="Verify fails\ncorrectly", shape=diamond];
green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
verify_green [label="Verify passes\nAll green", shape=diamond];
refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
next [label="Next", shape=ellipse];
red -> verify_red;
verify_red -> green [label="yes"];
verify_red -> red [label="wrong\nfailure"];
green -> verify_green;
verify_green -> refactor [label="yes"];
verify_green -> green [label="no"];
refactor -> verify_green [label="stay\ngreen"];
verify_green -> next;
next -> red;
}
Write one minimal test showing what should happen.
Requirements:
MANDATORY. Never skip.
Confirm:
Test passes? You're testing existing behavior. Fix test.
Write simplest code to pass the test.
Don't add features, refactor other code, or "improve" beyond the test.
MANDATORY.
Confirm:
After green only:
Keep tests green. Don't add behavior.
| Quality | Good | Bad |
|---|---|---|
| Minimal | One thing. "and" in name? Split it. | test('validates email and domain and whitespace') |
| Clear | Name describes behavior | test('test1') |
| Shows intent | Demonstrates desired API | Obscures what code should do |
"I'll write tests after to verify it works" - Tests written after code pass immediately. Passing immediately proves nothing.
"I already manually tested all the edge cases" - Manual testing is ad-hoc. No record, can't re-run.
"Deleting X hours of work is wasteful" - Sunk cost fallacy. Working code without real tests is technical debt.
"TDD is dogmatic, being pragmatic means adapting" - TDD IS pragmatic. "Pragmatic" shortcuts = debugging in production = slower.
| Excuse | Reality |
|---|---|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
| "TDD will slow me down" | TDD faster than debugging. |
| "Existing code has no tests" | You're improving it. Add tests for existing code. |
All of these mean: Delete code. Start over with TDD.
Before marking work complete:
Can't check all boxes? You skipped TDD. Start over.
Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
Never fix bugs without a test.
Production code → test exists and failed first
Otherwise → not TDD
No exceptions without your human partner's permission.