Test-Driven Development

Write one failing test, make it pass with minimal code, refactor. One test at a time.

When to Use

• Bug fixes (always — the regression test IS the fix verification)
• Parsers, validators, transformers (input→output functions)
• State machines, workflows, business rules
• Database migrations with data transformations
• Any code where "it works" isn't obvious from reading it

Skip for: Trivial edits, config changes, UI styling, documentation, dependency bumps.

The TDD Cycle

RED — Write One Failing Test

Write the simplest test that fails for the right reason.

Task Type	What "Minimal Failing Test" Means
Bug fix	Reproduce the exact bug. Test must fail with the same symptom the user reported.
Parser/transformer	One input → expected output. Start with the simplest valid input.
State machine	One state transition. Test the first transition in the happy path.
API endpoint	One request → expected response code + body shape.
Database migration	One record before → expected record after.
Validation logic	One valid input passes, one invalid input fails. Two tests minimum.

Verify the test fails. Run it. Read the failure message. If it fails for the wrong reason (import error, missing file, syntax error), fix the test — you haven't started RED yet.

GREEN — Write Minimal Code to Pass

Write the least code that makes the failing test pass. No more.

• Don't optimize. Don't refactor. Don't handle edge cases yet.
• If you're writing more than ~20 lines to pass one test, the test is too big. Split it.
• Run the test. It must pass. All existing tests must still pass.

REFACTOR — Clean Up Without Changing Behavior

• Extract duplicated code
• Rename unclear variables
• Simplify conditionals
• Run ALL tests after every refactor step — if anything breaks, undo.

Iterate

Add the next test (next edge case, next state transition, next input type). Repeat RED → GREEN → REFACTOR until the feature/fix is complete.

Test Design by Task Type

Bug Fixes

1. Write a test that reproduces the exact reported symptom
2. Confirm it fails with the same error the user sees
3. Fix the bug — test turns green
4. Add edge-case tests for related inputs that might trigger similar bugs

Parsers and Transformers

Build up complexity incrementally:

1. Simplest valid input → expected output
2. Empty/minimal input → expected handling
3. Malformed input → expected error
4. Complex/nested input → expected output
5. Boundary values (max length, special characters, unicode)

State Machines

Test one transition at a time:

1. Initial state → first valid transition → expected state
2. Each subsequent transition in the happy path
3. Invalid transitions → expected rejection
4. Terminal states → no further transitions allowed

Test Quality Checks

Before considering tests "done":

• Each test has exactly one reason to fail
• Test names describe the behavior, not the implementation
• No test depends on another test's side effects
• Edge cases covered: empty input, null values, boundary values, error paths
• Assertions check behavior, not implementation details

Red Flags — You Are Rationalizing

Thought	Reality
"I'll write tests after the implementation"	That's not TDD. Write the test first.
"This is too simple to test"	Simple code with tests stays simple. Simple code without tests becomes complex.
"I'll write all the tests first, then implement"	TDD is one test at a time. Write one, make it pass, then write the next.
"The test is obvious, I don't need to see it fail"	Run it. Seeing RED confirms your test actually tests something.
"I need to refactor first before I can test"	Write a characterization test for the current behavior first, then refactor.
"Edge cases can wait"	Edge cases found later cost 10x more. Add them during the cycle.

Transitions

Called by: mbscode:executing-plans, mbscode:subagent-driven-development (when plan steps include TDD patterns); mbscode:systematic-debugging Phase 4 (write failing test for the bug) During: Works alongside the calling skill — TDD is an execution technique, not a separate phase. Return to the calling skill when tests pass. Related: mbscode:writing-plans mandates TDD step patterns; mbscode:verification-before-completion requires the test evidence this skill produces.