tdd-workflow

# TDD Workflow A disciplined red → green → refactor loop. One failing test at a time, the minimum code to pass, then refactor under a green bar. This is a methodology skill — follow the loop exactly; do not batch. ## When to use Use when behavior can be expressed as assertions: business logic, parsers, APIs, algorithms, bug fixes (reproduce as a failing test first). Skip for throwaway spikes, pure UI layout, or exploratory prototypes with no maintenance horizon. ## The loop ### RED — write one failing test - Pick the **smallest** unspecified behavior. - Write one test asserting it. Run it. Confirm it fails **for the right reason** (assertion failure, not import/syntax error). - A test that passes immediately, or fails on a typo, is not a red. Fix and re-run. ### GREEN — minimum code to pass - Write the least code that makes that test pass — hardcoding is acceptable here. - Run the **full** test suite, not just the new test. Green means all pass. - Do not add untested code "while you're there." If you want it, it needs a test → back to RED. ### REFACTOR — improve under green - Remove duplication, clarify names, simplify structure. - Re-run the full suite after each change. Any red → revert the refactor, don't debug forward. - No behavior change here. New behavior is a new RED. Repeat until the feature's behaviors are all covered. ## Setup Detect the project's existing runner — do not introduce a new one. ```bash # JS/TS: npx vitest run | npx jest # Python: pytest -q # Go: go test ./... # Rust: cargo test ``` If no framework exists, ask which to add before starting; match the ecosystem default. ## Bug-fix mode 1. RED: write a test that reproduces the bug and fails. 2. GREEN: fix until it passes and nothing else breaks. 3. The reproduction test stays as a regression guard. Never fix a bug without a failing test that proves it existed. ## Test quality - One behavior per test; the name states the behavior. - Assert observable outcomes, not internal calls, unless the interaction *is* the contract. - Cover edge cases as their own REDs: empty, boundary, invalid input, async failure, concurrency. - A test you can't make fail by breaking the code tests nothing — delete or fix it. ## Anti-patterns - Writing implementation first, then tests to match it (that's not TDD). - Writing 10 tests then implementing — you lose the design feedback. - Skipping the "confirm it fails" step. - Refactoring and adding behavior in the same step. - Mocking so heavily the test passes even when the real code is broken. ## Done when All behaviors have failing-first tests that now pass, full suite is green, no untested production code, and the bug-fix tests are retained as regression coverage.