/stdd:tdd — TDD red-green-refactor loop

/stdd:tdd — TDD red-green-refactor loop

Feature: $ARGUMENTS

Setup

1. Read docs/specs/$ARGUMENTS.md. If it does not exist, stop:

   No spec found. Run /stdd:spec $ARGUMENTS first.

2. Determine test file location (pick one, be consistent within the project):

   • Co-located: src/$ARGUMENTS.test.<ext> (idiomatic for Bun, Vitest, Jest)
   • Separated: tests/test_$ARGUMENTS.<ext> (idiomatic for pytest)

   Remember this path — it is <test-file> in the RED and GREEN commands below.

3. Write the feature name to .tdd-in-progress in the project root:

   printf '%s\n' "$ARGUMENTS" > .tdd-in-progress
   

   This tells the guard hook to allow matching writes to src/ during this session.

Plan the first slice

Before writing any test, do a short planning pass on the spec.

• Public interface — sketch the function signatures, types, or module shape callers will use. The first test commits you to this shape; commit deliberately.
• Tracer bullet — pick the one acceptance criterion that is the smallest end-to-end slice. It need not be the most interesting one; it needs to prove the wiring works (imports, types, file layout).
• Priority — note which remaining criteria matter most if scope shrinks.
• Coverage map — list every acceptance criterion by AC-N ID in spec order with the test category it belongs to (happy path, edge, error, security). The list defines what "done" means; do not silently drop items.

State the plan and the coverage map, then confirm with the user before the first RED, unless you are running unattended.

Anti-pattern: do not slice horizontally

Even though the spec lists several acceptance criteria, do not draft all the tests up front and then implement them. Tests written in bulk verify imagined behavior — they test the shape of things rather than what the code actually does, and they pass when behavior breaks because they were calibrated to a guess.

One acceptance criterion → one test → one minimal implementation → repeat. Each cycle responds to what the previous one taught you about the code.

The loop

Work through the spec's acceptance criteria one at a time. Do not write the next test until the current one is GREEN and clean.

RED — write one failing test

Write a single test for the next acceptance criterion. Include the criterion's AC-N ID in the test's name or docstring so the coverage audit can find it mechanically:

• pytest function name: def test_AC_1_parses_empty_input(): ... (Python identifiers forbid hyphens, so use the underscore form).
• pytest docstring: def test_parses_empty_input(): """AC-1: parses empty input."""
• Bun / Vitest / Jest: test('AC-1: parses empty input', () => { ... })

AAA structure:

• Arrange — set up the inputs and preconditions
• Act — call the code under test
• Assert — check the result against the expected output

Run: ./scripts/run-tests.sh <test-file>

The test must fail. If it passes, it is not testing anything real — fix it before continuing. Fail for the right reason (missing implementation, not a broken test).

GREEN — make it pass

Write the minimum code to make that single test pass. Do not anticipate future tests. No extra features, no speculative abstractions.

Run: ./scripts/run-tests.sh <test-file>

The test must pass.

REFACTOR — clean up

Look at what you just wrote. Ask:

• Is there duplication with code from a previous iteration?
• Is a name unclear or misleading?
• Is a function doing more than one thing?
• Does this new code reveal something about existing code — a missing abstraction, a redundant path, an inconsistent name?
• Can a module be deepened — push complexity behind a simpler interface so callers see less?

If yes, fix it. If no, move on. Refactor is about the code you just touched, nothing else. Never refactor while RED — get to GREEN first.

Run: ./scripts/run-tests.sh

Full suite — no arguments. This is where regressions are caught. All tests must still pass. If any fail, revert the refactor — it was wrong.

MARK — record progress

When the full suite is green, tick this criterion in docs/specs/$ARGUMENTS.md: change its - [ ] to - [x]. The spec is the live progress record — a reviewer, a later session, or /stdd:review reads it to see what is done.

Check

Before starting the next cycle, confirm:

• The test describes behavior, not implementation.
• The test uses the public interface only.
• The test would still pass after a pure internal refactor of the code.
• The test carries the criterion's AC-N tag in its name or docstring.
• The code is minimal for this test — no speculative features.
• The criterion is marked [x] in the spec (MARK step done).
• You did not start drafting the next test while in the current cycle.

Next

Move to the next acceptance criterion. Back to RED.

Finish

When every acceptance criterion has a passing test:

1. Remove the .tdd-in-progress marker file.

2. Run ./scripts/run-tests.sh one final time. Show the full output.

3. Sweep docs/ for stale references. Outside the just-edited spec and the test files, grep for:

   • The spec's slug ($ARGUMENTS) and the new module's file path.
   • Names of exports, types, or config fields the spec added, renamed, or removed.
   • Phrases the spec retired ("not yet implemented", "documented gap", old warning text, old field names).

   For every hit, decide update or leave and say why. Code-fenced examples (JSON, snippets) are usually update — they are contracts a reader can copy. This catches the failure mode the test loop cannot: the suite stays green while prose elsewhere in docs/ rots.

4. Print the coverage audit — table plus Gaps section plus Coverage: N/M line. Format is defined in "Coverage audit format" in the stdd rules.

5. If Gaps lists unchecked criteria, the implementation is not complete. Go back to RED for them before declaring done.