Raw view: TDD Feature Loop

No invisible, zero-width, or bidi-control characters detected.

# TDD Feature Loop

Build the feature described in <feature> one behavior at a time. Each cycle adds exactly one failing test, makes it pass with the smallest change, then cleans up under green. Do not write implementation code before a failing test demands it; do not write a second test while the first is red.

<feature>
{{FEATURE_DESCRIPTION}}
</feature>

Test command: `{{TEST_COMMAND}}`. Tests live in `{{TEST_DIR}}`; source in `{{SOURCE_DIR}}`.

## Phase 0: Orient (no code changes)

1. Read the existing tests in `{{TEST_DIR}}` nearest to this feature. Note the framework, naming style, fixture pattern, and assertion library. You will match these exactly.
2. Run `{{TEST_COMMAND}}` once. Record the result. If the suite is already red, STOP and report; do not build on a broken baseline.
3. Decompose <feature> into a numbered list of observable behaviors, smallest first, each phrased as a test name ("returns empty list when no items match"). Aim for 3-8. Include at least one error or edge behavior.
4. **STOP POINT.** Present the behavior list and the baseline test result. Wait for approval or edits before writing any test.

**Artifact:** `BEHAVIORS.md` (or equivalent note) with the ordered list and a checkbox per behavior.

## Phase 1: Red

5. Take the first unchecked behavior. Write one test for it in the existing style. Literal inputs, hardcoded expected values, one act, assertions on outcomes.
6. Run `{{TEST_COMMAND}}`. **Check:** exactly one new failure, and it fails for the expected reason (missing symbol, wrong value), not a syntax error or fixture problem. If it passes, the behavior already exists or the test is wrong; investigate before continuing. If it fails for the wrong reason, fix the test, not the code.
7. Record the failure message verbatim in the behavior's entry.

## Phase 2: Green

8. Write the smallest change in `{{SOURCE_DIR}}` that makes the failing test pass. Hardcoding is acceptable if it is the smallest step; the next test will force generalization. Do not add handling for cases no test asks for.
9. Run `{{TEST_COMMAND}}`. **Check:** the new test passes and no previously passing test fails. If anything else broke, revert the implementation change and try a smaller step.
10. Check the behavior off.

## Phase 3: Refactor (under green only)

11. Look at the code touched in this cycle plus its immediate neighbors. Remove duplication the last two cycles introduced, improve a name that now reads wrong, or extract a function that has grown past one job. Change nothing observable.
12. Run `{{TEST_COMMAND}}` after each refactor step. **Check:** all green. If red, undo the last refactor step; do not "fix forward" during refactor.
13. Commit (or snapshot) with a message naming the behavior: `feat: <behavior>`.

## Loop

14. Return to Phase 1 with the next unchecked behavior. Continue until all are checked.
15. **STOP POINT.** If, during any cycle, you discover a behavior not on the list that the feature needs, add it to the list, mark it `[added: reason]`, and pause for approval before testing it. Do not silently expand scope.
16. **STOP POINT.** If a test cannot be made to pass without changing a public interface outside <feature>, stop and report the conflict with options.

## Phase 4: Close

17. Run the full suite one final time. Run the project's lint and type checks if present.
18. Review the complete diff against <feature>. Remove any code not demanded by a test. Confirm each test name still describes what it tests.
19. Produce the summary artifact.

**Final artifact:** a short report with: behaviors implemented (with test names), behaviors added mid-loop and why, anything deferred, the final test count before and after, and the commands to verify.

## Rules throughout

- Never modify a test to make it pass unless the test itself was wrong; if so, say so explicitly.
- Never skip the run after a change. The loop's value is in the feedback, not the ceremony.
- Prefer a general solution once two tests push in the same direction; do not keep special-casing.
- If the tests are slow (over 2 minutes), run only the relevant file during the loop and the full suite at Phases 0 and 4.