# Tdd Workflow

> Runs red-green-refactor with tests first, no production code without a failing test, and explicit loophole closure. Use this skill when implementing behavior with TDD or when tempted to code before tests. Do not use when/for test strategy/pyramid selection alone (use testing-strategy) or mutation scoring (use mutation-testing).

- Skill: `jagreehal/tdd-workflow` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jagreehal/tdd-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/tdd-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/tdd-workflow

---


# 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](references/state-machine.md) — per-state pre/post-conditions, hardcode table, diagram. Read when entering a state or stuck on transitions.
- [references/examples.md](references/examples.md) — fn(args, deps) test template, meaningful vs setup failures, no-vi.mock. Read when writing the RED test.
- [references/rationalizations.md](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).