tdd

Step 1: Confirm the interface

Before writing anything:

1. What is the public interface? (function signature, HTTP route, module exports)
2. Which behaviors matter most? List them in order of how badly you'd want to know if they broke.
3. What does a "caller" look like? Write one example call in prose.

If the user has not supplied these, ask — one round, 1–3 questions.

Step 2: Tracer bullet

Pick the first behavior — usually the happy path for the most common input. Write one test that exercises it end-to-end through the public interface. Run it. It must fail (RED). If it passes, the test is not testing what you think it is — fix the test before writing any code.

Then write the minimum code to make it pass. "Minimum" means: if hard-coding return 42 makes the test pass, hard-code return 42. You will generalize on the next cycle. Run the test. It must pass (GREEN).

This proves the end-to-end path works — test harness, imports, wiring, build. Everything from Step 3 onward is incremental.

Step 3: Red-green loop

Pick the next behavior. Write one test that pins it. Run — RED. Write the minimum code that makes it pass without breaking prior tests. Run — GREEN.

Guidelines for picking the next behavior:

• Alternate happy-path-variant and edge-case tests — don't do all happy paths then all edges.
• Stop adding happy paths when they stop revealing new code. Move to errors.
• If the next test would require no new code, you have hit the end of this slice — skip to Step 4.

Guidelines for writing the test:

• One assertion per concept (multiple expect calls that describe one behavior are fine).
• No mocking of internals. Mock external I/O (network, filesystem, clock) only when necessary.
• The test name reads as a sentence: "rejects requests missing an auth header".

Guidelines for writing the code:

• Minimum to pass. If there are three cases and two are untested, write only the one that's under test.
• Copy-paste is fine on the first and second occurrence. Extract on the third.

Step 4: Refactor while GREEN

Now that the behavior is pinned, clean up. Extract duplicated logic. Rename unclear variables. Deepen the module — move responsibilities behind the interface until the internals stop leaking into the test.

Rules:

• Every refactor keeps every test GREEN. Run tests after each small change.
• If a refactor would require changing a test, the test was coupled to implementation — either the test is wrong, or the interface you thought you were pinning is actually different. Fix the test first, then refactor.
• Don't refactor speculatively. Extract around real duplication and real seams, not imagined ones.

Step 5: Close the slice

When the behavior the task plan specified is fully under test and the code is clean:

1. Run the full test suite — not just the tests you wrote. Verify no regressions.
2. Append a one-line summary of what is now pinned to .gsd/KNOWLEDGE.md if the behavior is non-obvious or the test surfaced a trap future agents should know about.
3. Use gsd_* tools to mark the task complete — do not edit checkboxes by hand.