test-driven-development

name	test-driven-development
description	Use when implementing features or bugfixes where a failing test first is the strongest and most practical way to prove behavior before implementation code

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

TDD is strongly preferred for:

• bug fixes
• shared or reusable logic
• business rules / transformations / parsing
• code with meaningful regression risk
• behavior that is hard to trust from inspection alone

TDD is optional, with explicit justification, for:

• trivial low-risk presentation changes
• isolated text/config updates with low behavior risk
• cases where a higher-signal verification method is more appropriate than a narrow failing test first

The Strong Default

WHEN TDD IS THE BEST AVAILABLE PROOF, DO NOT WRITE PRODUCTION CODE BEFORE A FAILING TEST

If you skip TDD where it clearly should have been used, treat that as a process failure and correct it.

Red-Green-Refactor

RED - Write Failing Test

Write one minimal test showing what should happen.

Verify RED - Watch It Fail

MANDATORY. Never skip.

Confirm:

• Test fails
• Failure message is expected
• Fails because feature missing, not typo

GREEN - Minimal Code

Write simplest code to pass the test.

Don't add extra features or refactor beyond what the test needs.

Verify GREEN - Watch It Pass

MANDATORY.

Confirm:

• Test passes
• Other relevant tests still pass
• Output is clean

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Common Rationalizations

Excuse	Reality
"I'll test after"	Tests passing immediately prove nothing
"Already manually tested"	Ad-hoc ≠ systematic
"Too simple to test"	Simple code breaks too
"Need to explore first"	Fine. Throw away exploration, then start with TDD
"Any change must use TDD"	Use TDD strongly, but choose the best verification method for the actual risk

Red Flags - STOP and Reassess

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Rationalizing "just this once"

When these appear in a context where TDD is clearly appropriate, stop and start over with TDD.

If the change is genuinely low-risk and another verification method is better, explicitly state that choice and use the stronger evidence path instead of cargo-cult TDD.

Verification Checklist

Before marking work complete:

• Used TDD for bug fixes and other changes where failing-test-first is the strongest practical proof
• When TDD was used, watched each test fail before implementing
• When TDD was used, each test failed for the expected reason
• When TDD was used, wrote minimal code to pass each test
• If TDD was not used, recorded why another verification method was more appropriate
• All relevant tests pass

Final Rule

Use TDD when it is the best tool for proving behavior and preventing regression.
If another verification path is stronger for the actual risk, choose it deliberately and explain why.