follow-tdd

name

follow-tdd

description

This skill should be used when implementing any feature, fixing any bug, or changing any code behavior, before writing the implementation code. It also applies when the user says "TDD", "test first", "red-green-refactor", "write the test before the code", when authoring automated end-to-end browser tests (Playwright) for a user journey, and after the fix skill has reproduced a bug's root cause, to write the regression test first. It should not be used to diagnose a reported bug (use fix; it hands off here), for pure configuration changes, documentation, static content, or for runtime-verifying an already-built change (use the verify skill for that).

Purpose

Drive every behavior change with a failing test written first. Tests are proof; "seems right" is not done. Do not write any production code until a failing test exists for it, and do not declare work complete until the Verification Checklist passes.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before its test? Delete it. Start over.

No exceptions:

• Do not keep it as "reference"
• Do not "adapt" it while writing the tests
• Do not look at it
• Delete means delete

Why this severe: code written first biases the tests toward what you built instead of what is required, and tests written after pass immediately, which proves nothing. The deletion is not punishment; it is the only way the rewritten code is actually derived from the tests.

Violating the letter of this rule is violating its spirit. Arguments that a workaround honors the spirit are the failure mode, not an exception.

The only exceptions, each requiring user confirmation first: throwaway exploration spikes (thrown away before the real implementation starts with TDD) and generated code.

Workflow

Copy this checklist and track each cycle:

TDD Cycle:
- [ ] 1. Behaviors listed and prioritized
- [ ] 2. RED: one failing test written
- [ ] 3. Verify RED: watched it fail for the right reason
- [ ] 4. GREEN: minimal code to pass
- [ ] 5. Verify GREEN: test passes, full suite green
- [ ] 6. REFACTOR: clean up, tests stay green
- [ ] 7. Repeat for next behavior

1. List the behaviors

Before any test, list the behaviors to verify (not implementation steps), using the project's existing domain vocabulary.

For every feature, the coverage floor is three tests, and naming them is how you find the behaviors:

• Golden path: the feature does what it is for, with valid input under expected conditions. The proof it works at all.
• Error case: invalid input or a failure condition is handled as designed (rejected, returns an error, throws, degrades), not swallowed or crashed. The proof it fails safely.
• Edge case: the boundary where the logic is most likely to break (empty, null, zero, the maximum, the off-by-one, the concurrent call, the duplicate). The proof it holds at the corners.

This skill is the canonical home of the three-test floor; other skills and documents that cite golden path, error, and edge coverage reference this definition rather than restating it.

This is a floor, not a ceiling. A feature with branching logic or several failure modes needs an error and an edge test per branch; a trivial pure function may genuinely need only the three. Above the floor, prioritize critical paths and complex logic over exhaustive enumeration, and confirm priorities with the user when the interface design is not already settled. Skipping a category is a decision to state, not a default to drift into: "no error case because the type system makes invalid input unrepresentable" is a valid call, silently testing only the golden path is not.

The three categories are per-behavior; a feature that spans a user-facing flow has one more level to cover. The complete user journey is itself a behavior: the end-to-end path a real user walks to accomplish the goal (arrive, move through each step in realistic order, reach the end state), exercised by an integration or e2e test against the assembled system, not only each unit in isolation. Enumerate the primary journey and any flow where the steps interact or carry state forward, because a suite where every unit passes but the assembled journey was never run has a coverage gap: the flow can break at a seam where each step passes on its own.

2. RED: write one failing test

One test, one behavior, through the public interface.

• One behavior per test; an "and" in the test name means split it
• The name reads like a specification: "rejects empty email", not "test1" or "validation works"
• Real code paths; test doubles only at system boundaries (see references/test-quality.md)
• Assert on outcomes (state), not on which methods were called internally; interaction assertions break on refactors even when behavior is unchanged

3. Verify RED: watch it fail

Mandatory, never skip. Run the test and confirm:

• It fails, not errors: a syntax error or broken import is not a valid RED
• It fails because the feature is missing, with the failure message you expected

If the test passes immediately, you are testing behavior that already exists; fix the test, not the code. If you cannot explain why it failed, you do not know what it tests.

4. GREEN: minimal code to pass

Write the simplest code that makes this test pass. Do not anticipate future tests, add options, or improve neighboring code; speculative generality is how minimal implementations become over-engineered ones (YAGNI).

5. Verify GREEN: watch it pass

Run the test: it passes. Run the full suite: nothing else broke. Output is pristine: no new errors or warnings. If the test fails, fix the code, not the test. Do not re-run an unchanged passing suite for reassurance; re-run only after edits.

6. REFACTOR: clean up on green only

Remove duplication, improve names, extract helpers. Run tests after each refactor step; behavior does not change. Never refactor while RED.

7. Repeat

Next behavior, next failing test. Each cycle is a complete vertical slice.

Vertical Slices, Not Horizontal

Do not write all the tests first and then all the implementation:

WRONG (horizontal):  test1, test2, test3 ... then impl1, impl2, impl3
RIGHT (vertical):    test1 -> impl1, test2 -> impl2, test3 -> impl3

Tests written in bulk test imagined behavior, not actual behavior; you commit to test structure before the implementation has taught you anything. Each vertical slice is a tracer bullet: one test, one implementation, then the next test responds to what that cycle revealed. This is the same one-behavior-at-a-time ordering plans use, so a plan that lists work in tracer-bullet order is implemented in that same order, not batched into all-tests-then-all-code.

The Prove-It Pattern (Bug Fixes)

When a bug arrives, do not start with the fix. Write a test that reproduces the bug and watch it fail; that failure is the proof the bug exists and the proof your fix works when it flips to green. Then run the full suite for regressions. Never fix a bug without a reproduction test: an untested fix can be a coincidence, and the regression returns silently.

For complex bugs, consider spawning a subagent to write the reproduction test from the bug report alone, without knowledge of the planned fix; tests written blind to the fix are harder to accidentally bias.

Good Tests

Quality	Do	Not
Minimal	One behavior per test	"and" in the name
Specified	Name describes expected behavior	"works", "handles errors"
Behavioral	Public interface, observable outcomes	Private methods, call sequences
Self-contained	DAMP: each test readable alone	Setup buried in shared helpers
Structured	Arrange-Act-Assert	Interleaved setup and assertions
Real	Real implementation > fake > stub > mock	Mocking your own modules

Test Anti-Patterns

These failures make the suite pass while proving nothing. Run the gate question before you write the test; if the honest answer is the wrong side of it, stop and rework, because the test is about to verify the wrong thing.

Anti-pattern	Why it is wrong	Gate question
Testing mock behavior	A *-mock assertion proves the mock is present, not that the real code works; it fails only when the mock is removed	Am I asserting on real behavior or on the mock's existence?
Test-only methods in production	A method called only from tests pollutes the production API and is dangerous if real code ever calls it	Is this method used anywhere outside tests?
Mocking without understanding	Stubbing a method whose real side effect the test depends on makes the test pass for the wrong reason or fail mysteriously	What side effects does the real method have, and does this test depend on any of them?
Incomplete mocks	A mock with only the fields you happened to read hides the rest of the real shape; downstream code reading an omitted field fails silently while the test stays green	Does this mock mirror every field the real response returns?
Interaction assertions	Asserting which methods were called couples the test to internals, so it breaks on refactors that change nothing observable	Am I asserting an observable outcome (state) rather than a call sequence?

When adding any mock, test double, or test utility, read references/test-quality.md first; it holds the worked examples, fixes, and the full gate functions behind this table.

Common Rationalizations

Excuse	Reality
"Too simple to test"	Simple code breaks. The test takes 30 seconds and documents intent.
"I'll write tests after"	Tests that pass immediately prove nothing; you verify what you built, not what was required.
"Tests-after achieve the same goals"	Tests-after answer "what does this do?"; tests-first answer "what should this do?"
"I already manually tested it"	Ad-hoc, no record, cannot re-run. Tomorrow's change breaks it silently.
"Deleting X hours of work is wasteful"	Sunk cost. Keeping unverified code is the real debt; you cannot trust it.
"Keep it as reference while I write tests"	You will adapt it. That is testing after. Delete means delete.
"I need to explore first"	Fine. Throw the exploration away and start the real implementation with TDD.
"The test is hard to write"	Hard to test means hard to use. Listen to the test; simplify the design.
"TDD will slow me down"	Debugging in production is slower. The test finds the bug before commit.
"It's about the spirit, not the ritual"	The ritual is the spirit. Watching the test fail is the only proof it tests anything.
"The behavior is already discovered; rebuilding just risks new bugs"	The understanding survives deletion and makes the rebuild fast. Where the rebuild diverges from the deleted code is exactly where the deleted code could not be trusted.
"Just this once"	Every exception becomes the norm under the next deadline.
"Production is down, no time for a test"	The reproduction test takes minutes and proves the emergency fix actually fixes the emergency. Shipping an unproven fix to a down system risks a second outage.

Red Flags: STOP and Start Over

• Code written before its test
• Test passes on its first run
• Cannot explain why the test failed
• "I'll add tests later" or "tests in a follow-up PR"
• "I already manually tested it"
• "Keep it as reference" or "adapt the existing code"
• "Already spent X hours, deleting is wasteful"
• "This case is different because..."
• Mock setup longer than the test logic
• Skipping or disabling tests to make the suite pass

All of these mean: delete the code, restart with TDD.

When Stuck

Problem	Solution
Do not know how to test it	Write the wished-for API call and the assertion first; ask the user if still stuck
Test too complicated	The design is too complicated; simplify the interface
Must mock everything	Code too coupled; inject dependencies
Test setup is huge	Extract helpers; if still complex, the design needs work

Verification Checklist

Before declaring the work complete:

• Every new behavior has a test
• Every feature covers all three cases: golden path, error case, and edge case (or a stated reason a category does not apply)
• Watched each test fail before implementing, for the expected reason
• Minimal code written per test, no speculative features
• Full suite passes with pristine output
• Bug fixes include a reproduction test that failed before the fix
• Tests assert through public interfaces on observable outcomes
• No tests skipped or disabled
• For a user-facing change, the complete user journey was walked end to end and observed working (live or via an e2e test), not just the isolated behavior

Cannot check every box? TDD was skipped somewhere; the unchecked box names where to restart.

After Green: Validate Live

Green tests prove the logic; they do not prove the running system. For a change with a runnable surface, the suite exercises code paths while the rendered UI, the live endpoint, and the real serializer go unobserved. Once the cycle is green, hand off to live validation, the step that follows red, green, refactor:

• Web UI: validate-web drives a real browser against the dev server.
• HTTP API: validate-api sends real requests against the running service.

Validate the complete user journey, not just the one behavior you changed: walk the full multi-step flow a real user takes to reach the goal the change serves (arrive, move through each step, act, see the end state), in realistic order, because a change that passes in isolation can still break the flow it lives inside, and the experience the user actually has is the sum of those steps in sequence. This is also the bar for calling the work done: for a user-facing surface, "done" means the full flow was walked and observed working, not just a green suite.

A pure library or a refactor with no behavioral surface has nothing to validate live; say so rather than inventing a step.

Example: Bug Fix

Bug report: empty email accepted by the signup form.

// RED: reproduction test
test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

$ npm test signup.test.ts
FAIL: expected 'Email required', received undefined   # bug confirmed

// GREEN: minimal fix
function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

$ npm test signup.test.ts
PASS                                                   # fix proven
$ npm test
PASS (all)                                             # no regressions

REFACTOR: extract field validation only if duplication actually exists, with tests staying green.