Test Driven Development

Test-Driven Development

> Verification status: VERIFIED under combined time + authority + simplicity pressure (2/2 baseline wrote implementation with no test at all; 2/2 with skill wrote and watched a failing test first). Content below is pressure-tested — behavioral edits require a fresh RED→GREEN cycle.

Overview

Write the test first. Watch it fail. Write the minimal code to pass. Refactor. The order is the whole point: a test written after the code proves the code does what it does, not what it should do.

Core principle: The failing test defines "done" before "done" can be rationalized.

Violating the letter of this rule is violating the spirit of it. There is no version of "I'll test after" that produces a test-first result.

The Iron Law

NO IMPLEMENTATION CODE BEFORE A FAILING TEST

Wrote code first? Delete it. Start over with the test. Not "adapt it," not "keep it as reference," not "look at it while writing the test." Delete means delete.

The Cycle

1. RED — Write one test for the next behavior. Run it. Watch it fail for the right reason (asserting the behavior, not a typo or missing import).
2. GREEN — Write the minimal code to pass that test. Nothing speculative.
3. REFACTOR — Clean up with the test green as your safety net. Re-run.

A test that passes the moment you write it tested nothing — you never saw it fail, so you don't know it can.

What Earns a Test

Not everything. A test written to satisfy process costs maintenance forever.

• Earns one: any branch, side effect, boundary, contract, or validation someone could get wrong.
• Earns none: trivial forwarding, constants, human prose, generated code you don't own.
• Cannot be tested by text-matching: scripts, prompts, and skills are tested by running them and observing behavior, never by grepping their source for a string. See references/writing-good-tests.md.

Before writing the test body, name the production change that would make this test fail. If you can't name one, or the only thing that would fail it is an intentional decision (a renamed constant, reworded message), you're writing a change detector — redesign it around observable behavior.

Full discipline — mirror assertions, mock levels, mutation check, warning signs — lives in [references/writing-good-tests.md](references/writing-good-tests.md). Load it when writing tests, adding a mock, or adding a test helper.

Rationalization Table

| Excuse | Reality | |---|---| | "Too simple to test" | Simple code breaks. The test takes 30 seconds. | | "I'll test after" | Tests-after ask "what does this do?" Tests-first ask "what should this do?" | | "I already tested it manually" | Manual once ≠ regression-proof forever. Encode it. | | "The test passes already" | Then you never watched it fail. You don't know it works. | | "It's about spirit not ritual" | The ritual is the spirit. The order is what makes it TDD. | | "Writing tests first is slower" | It's slower to the first line of code and faster to working code. You are measuring the wrong end. | | "I'll know the design after I build it" | Then the test locks in the design you happened to reach, not the one you needed. | | "Deleting working code is wasteful" | Untested code isn't working code. It's code that hasn't failed yet. | | "This is different because…" | It isn't. Write the test. |

Red Flags — STOP and Start Over

• Implementation code exists and no test failed first.
• "I'll add tests once it works."
• A new test that passed on the first run.
• A test whose expected value is computed by the code under test.
• A test that asserts a file contains a string, instead of running the thing.

All of these mean: delete the code, write the failing test, start the cycle.

For Bugfixes Specifically

The failing test is the reproduction. systematic-debugging gets you a reliable repro; encode that repro as the RED test before you fix anything. A bugfix without a test that fails before it and passes after it is a bugfix you cannot prove.

Common Mistakes

• Testing too much at once. One behavior per RED. Big tests hide which behavior is missing.
• Skipping the failure observation. Always see RED before GREEN — it's your proof the test can fail.
• Over-building in GREEN. Minimal means minimal. Speculative code is untested code (reducing-complexity).
• Stopping at green. Tests passing is not the same as the feature working — verifying-before-done.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kumosan2
• Source: kumosan2/Fablepowers
• License: MIT

Install and usage instructions live in the source repository linked above.