Test-Driven Development
When to use
- Skip disposable spikes and non-behavioral content or config. Behavior from a spike that is then accepted gets rebuilt under a check.
- High-risk target code waits for its approved migration and assurance contracts and their entry gates. Work authorized only to build a check cannot edit the target or satisfy entry on its own.
Step 1: Before the first test command
If the test command reaches outside the repository (a shared service, a real database, the network, a path outside the worktree), write down what it touches: the environment and data, the effects, the time and resources, the cleanup, and your authority for each. Never aim a test at a shared or production surface not written here. If it stays entirely inside the repository, write no record.
Pin down the public interface and the behavior it promises, from the task, the spec, or the approved design. If the meaning is unresolved, invoke
clarifying-intent. Never guess it into a test.Pick the cycle:
- For new or intentionally changed behavior, go to Step 2.
- For behavior that must survive a change unchanged, go to Step 3.
- For a bugfix, go to Step 2, starting from its runnable reproduction.
- For a task whose deliverable is tests for behavior that already works,
go to Step 3 with the new tests as its check, run items 1 to 4, read
references/preservation-cycle.mdwhen you pick the oracle, then continue at Step 4: the deliberate divergence the suite must catch stands in for RED.
Never invent a failure for behavior that already works.
A task that moves
parse_priceinto themoneymodule and also makes it reject a negative amount is two cycles: Step 3 for the move, Step 2 for the rejection. One test that fails because the import path moved proves neither.If the layer has no test harness, move its rules into units and test-drive those. The wiring left without a RED stays pending under the hard stops: report it and how you checked it, then ask whether to add a harness (naming its dependencies and config cost) or to accept the wiring as an unverified exception, and end the turn.
Step 2: New behavior, RED then GREEN
List the cases the approved behavior covers before the first test: the ordinary one, each input's boundaries (empty, zero, the limit, one past it), each failure the interface promises. Write one test for the next case, one cycle each; a case left untested is deferred work for Step 4.4. Nearby behavior that must stay unchanged takes Step 3.
If the behavior is a detector (a lint rule, validator, or scanner), pin, in the same test, an input it must flag and a near-miss it must pass; a separate near-miss test gets its RED from a detector that over-matches.
If the change adds an in-progress flag or lock, run one Step 2 cycle per public method that touches the state it guards, calling it while the operation is in flight. Take that list from the state, not from the misuse you expect.
Run it through the project's real test command.
Read the failure. Confirm it is the right one: the test was discovered, executed, and failed at the intended assertion.
RED, right reason: FAIL test_rejects_expired_token — AssertionError: expected 401, got 200 RED, wrong reason: ERROR test_rejects_expired_token — ImportError: cannot import name 'verify' Not RED: 1 skipped, 0 failedIf the wrong reason is a missing symbol, add the smallest stub that cannot pass (it returns a wrong value) and rerun, so the failure is at the intended assertion. If a stub cannot be added, confirm the runner collected exactly the tests you wrote before reading the failure.
If it passes first run, find which holds: the behavior already exists (Step 1.3's last route), the assertion cannot fail for this code (fix the test), or code ran ahead of the test (remove it and rerun).
On a wrong reason whose cause is not directly visible, or an unexplained result, invoke
debuggingbefore any product code, passing back the attempt count its ledger recorded for this cycle when the cycle came fromdebugging.Keep the output.
Record the test's identity, the identity of the evaluator, and the expected observable as of this RED, under
.sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/. If any of the three changes later, the cycle is invalid: restart and reach RED again.Write only the code that makes this test pass.
Run the new test, then the project's whole test command. Both must be green. Report every failing test by name, unrelated ones included; stop, and do not filter.
Refactor under green. Rerun both. An intended behavior change is a new RED cycle under the approval that owns it.
Step 3: Preserved behavior, GREEN, then a deliberate RED, then GREEN
- Take the characterization check the task or plan accepted; for high-risk work, use the differential check from the assurance matrix. An inherited green suite counts only once it has been accepted as covering the preservation contract independently of the target. Strengthen smoke-only coverage before the first checkpoint.
- Run it on the current behavior. See it green. Keep the output.
- Introduce one controlled, representative divergence. Run the same check. Watch it go red the way you intended. Keep the output.
- Restore the exact state. Watch it go green again.
- Transform one slice, keeping that check green. Read
references/preservation-cycle.mdwhen you pick the oracle, when you meet the generator or config case, or when you decide which evidence to keep.
Step 4: Close the cycle
- If chronology is part of the claim, use an external observer or immutable checkpoints that the evaluator reruns. Logs written by the state under check are not evidence. Never write checkpoint history after the fact.
- Restore only the mutations this task made whose pre-state you recorded.
Leave anything else pending for
finishing-a-branch. Never delete inherited, shared, or user state to manufacture a cycle. - REQUIRED SUB-SKILL: invoke
verification-before-completionon the exact state you are about to call done. This cycle's check is one row of that skill's evidence record, not the whole record. - Return to whatever invoked this skill: a plan task, a worktree checkpoint,
or a fix under
debugging. In that report, list each piece of work you deferred during the cycle with the condition that closes it. Run no commit, push, or PR here.
Gotchas
- A
debuggingdetour does not reset its attempt count. Handing the count back on every wrong-reason RED is what letsdebugging's circuit breaker trip at all.
Hard stops
- New behavior code created by the current work has no observed behavior RED.
- A new-behavior test passes first run, or fails only because the test cannot execute.
- A preservation oracle was never seen green, never made red by a deliberate divergence, or derives expected results from the target it judges.
- A preservation checkpoint contains no new oracle even though inherited tests were never accepted as covering the preservation contract.
- A behavioral generator or config change tests only text presence or generated file existence.
- A test or evaluator, expected observable, corpus, or oracle changed after its RED or falsification without invalidating and restarting that cycle.
- A command or divergence lacks authority for its environment, data, effects, or cleanup, or lacks verified restoration.
- Throwaway or out-of-cycle code is being copied into the product.
When you are tempted to skip
| The thought | The reality |
|---|---|
| "Too simple to test" | Simple behavior still breaks; use the smallest real check. |
| "I'll write the test after" | For new behavior, that records the implementation instead of leading it. |
| "The port already works, so I need a fake RED" | No: start green, falsify the independent oracle, restore, then preserve it. |
| "I tested it by hand" | An unrepeatable observation cannot guard the next change. |
| "I'd lose the code I wrote" | Revert only your out-of-cycle implementation; sunk cost is not evidence. |
| "The test is hard to write" | The interface or oracle is exposing a design problem; fix that seam. |
| "There's no test framework" | Use the smallest executable assertion that can fail. |
| "It's just generated/config code" | Test the behavioral source and regeneration contract, not text presence. |
Common mistakes
- Testing internals or mock calls instead of public behavior. Read
references/reference.mdandreferences/mocking.mdwhen a test reaches past the public interface.