TDD Workflow

Critical rules

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

• Write code before the test? Delete it. Start over. No "reference", no "adapt", no looking at it.
• Every message starts with current TDD state: ⚪ PLANNING | 🔴 RED | 🟢 GREEN | 🔵 REFACTOR | 🟡 VERIFY | ⚠️ BLOCKED | 🔥 VIOLATION
• Verify RED (watch fail) and Verify GREEN (watch pass) are mandatory. Never skip.
• Implement only what the error message demands; hardcode when one test allows it.
• Never change the test to match implementation. Fix the code.
• No vi.mock() for app logic — inject deps, mock with vitest-mock-extended.
• Before long examples, rationalizations, or full state post-conditions, read the matching resource below.

Workflow

1. PLANNING — Write a failing test for the requirement (fn(args, deps) + typed mocks). Run it. Confirm meaningful failure (assertion, not import/setup). Show failure verbatim. → RED
2. RED — Announce minimal-implementation check (could hardcode?). Implement only what the error demands. Run test + typecheck + lint. Confirm pass. → GREEN
3. GREEN — Assess against fn-args-deps, result-types, naming. Need design cleanup? → REFACTOR. Else → VERIFY
4. REFACTOR — One improvement at a time (extract deps type, type errors, domain names). Keep green after each. → VERIFY
5. VERIFY — Full suite + lint + typecheck + build. Show output. All pass → COMPLETE. Failures route back (tests→RED, lint→REFACTOR, build→BLOCKED)
6. BLOCKED — Explain blocker, prior state, attempt. Stop. Wait for user. Never improvise past the gate.
7. VIOLATION — Announce 🔥 TDD: VIOLATION, name the rule broken, recover to correct state with user permission.

Bug fixes: reproduce with a failing test first (pair debugging-methodology). Test craft in RED: writing-tests. Pyramid placement: testing-strategy.

Resources

• references/state-machine.md — per-state pre/post-conditions, hardcode table, diagram. Read when entering a state or stuck on transitions.
• references/examples.md — fn(args, deps) test template, meaningful vs setup failures, no-vi.mock. Read when writing the RED test.
• references/rationalizations.md — excuse→reality and red flags. Read when tempted to skip TDD.

Validation

• Every message prefixed with TDD state
• Failing test existed before production code (or code was deleted)
• RED failure watched and shown; GREEN pass watched and shown
• Implementation matched only the current error; no anticipatory logic
• VERIFY ran full suite + lint + typecheck (+ build) with output shown
• Deps mocked via mock<DepsType>(), not vi.mock for app modules

Constraints

• Not for pure config/docs/static content with no behavior change.
• Throwaway exploration is fine only if deleted before real TDD starts.
• Adjacent: writing-tests (RED craft), testing-strategy (layer choice), fn-args-deps, result-types, debugging-methodology, mutation-testing (end-of-phase gate, not per-increment).