---
id: frankify-app/skills/tdd
version: "10240aeb"
license: MIT
install: manual
updated: 2026-07-27
---

# tdd — tdd guides you through writing tests before implementation using the red-green-refactor workflow. Each cycle commits a failing test marked red, then minimal passing code marked green, with refactoring only after all tests pass. The skill enforces behavioral testing over implementation details and includes commit hygiene checks to keep your tree lint-clean at every step.

Publisher: frankify-app · Stars: 0 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/frankify-app/skills`

## SKILL.md

# Test-Driven Development

Write test first. Commit it red. Write minimal code to pass. Commit green. Refactor.

**Core principle:** tests verify behavior through public interfaces, not implementation. Code can change entirely; tests shouldn't. A test that breaks when you rename an internal function — with no behavior change — was testing implementation. Delete it.

No watched failure = no proof the test tests the right thing. Commit history is the evidence; hooks check its structure.

See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.

## Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST COMMITTED FIRST.

Wrote code before the test? Delete it. Implement fresh from tests. Delete means delete. Exceptions (throwaway prototypes, generated code, config) need human sign-off. Thinking "skip TDD just this once"? That is rationalization.

## 1. Plan (before any code)

Use the project's domain glossary so test names and interface vocabulary match the codebase; respect ADRs in the area you touch.

- List the *behaviors* to test, not implementation steps. Prioritize critical paths and complex logic — you can't test everything.
- Design interfaces for [testability](interface-design.md); identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
- Confirm the public interface and the priority behaviors with the user, then proceed.

## 2. Vertical slices, not horizontal

DO NOT write all tests, then all implementation. That is horizontal slicing and it produces crap tests: written in bulk they test *imagined* behavior and the *shape* of things (signatures, data structures), go insensitive to real changes, and commit you to test structure before you understand the code.

Work in vertical slices — one test → one implementation → repeat. Each test responds to what the last cycle taught you.

```text
WRONG (horizontal):  RED: t1 t2 t3 t4   GREEN: i1 i2 i3 i4
RIGHT (vertical):    t1→i1  t2→i2  t3→i3 ...
```

The first slice is a tracer bullet: it proves the path works end to end.

## 3. Commit protocol

One behavior = one RED commit + one GREEN commit. Multiple cycles per branch is fine; prefer one cycle in flight in Go/Rust repos (see markers).

**Every commit — RED included — leaves the tree lint-clean.** After each
commit, run the repo's full hook suite over the whole tree (e.g.
`prek run --all-files`): exit code 0 and no files modified. An auto-fixer
changing files IS a failure — apply the fix and amend it into the commit that
introduced the problem before starting the next cycle. CI evaluating only the
PR head never excuses a dirty intermediate commit; per-commit hygiene is
verified here, at commit time, or not at all.

### STUB commit (only when the RED test needs a missing API surface)

A RED commit is red on **tests only**: lint, format, and type checks still
pass on it. When the new test calls a function, method, or parameter that does
not exist yet, type checking would fail — so first commit a minimal
signature-only stub as its own commit, prefix `chore(stub):`. Signature +
docstring, zero behavior: a new callable raises `NotImplementedError`; a new
parameter is accepted and ignored. This is the one sanctioned exception to the
Iron Law: a stub defines *interface*, and must contain no *implementation* —
any logic in a stub commit is production code without a failing test. Skip
this step entirely when the surface already exists.

### RED commit

- Write one failing test. One behavior, clear name, real code — no mocks unless unavoidable.
- Run it *unmarked*; watch it fail for the **right reason** (feature missing — behavior wrong, assertion fails, or the stub's `NotImplementedError` — never a typo, import error, or missing symbol). Passes immediately? It tests existing behavior — fix the test.
- Add the marker (below), suite green, commit. Tests only, prefix `test(red):`.

| Language | Marker | Strict? |
| --- | --- | --- |
| Python (pytest) | `@pytest.mark.xfail(strict=True)` | yes — XPASS fails suite |
| TS/JS (vitest) | `test.fails(...)` / `it.fails(...)` | yes |
| TS/JS (jest) | `it.failing(...)` | yes |
| Go | `//go:build red` + `TestRed` prefix + `red-tests` job | aggregate only |
| Rust | `#[ignore = "red"]` + `red_` prefix + `red-tests` job | aggregate only |
| Other | find a strict expected-failure mechanism; none exists → commit unmarked, tell the human the repo lacks red enforcement | n/a |

Go/Rust build-tag/ignore markers *exclude* tests from the normal suite, so a `red-tests` CI job must run only the marked tests and expect failure (no-op when none exist). Its exit code is aggregate: two red tests in flight, one wrongly passing → the job still passes. Strict markers catch this per-test; the job doesn't.

### GREEN commit

- Simplest code that passes. YAGNI — no speculative generality.
- Remove this cycle's red markers. No other test changes in this commit.
- Full suite green, output pristine. Fails? Fix the code, not the test. Prefix `feat:`/`fix:`.

### REFACTOR (after green only)

Remove duplication, improve names, extract helpers, deepen modules. Tests stay green, no new behavior, separate commit. **Never refactor while red.** Then start the next cycle.

After all tests pass, look for [refactor candidates](refactoring.md):

## Enforcement — and its limits

`lint-red.sh` (ships with skill; wire into prek + CI): `staged`/`commit` modes check that `test(red):` commits touch only test files and add a marker, others add none; `merge` mode rejects any markers in tree; if Go/Rust markers are present, a `red-tests` job must exist.

Hooks verify commit *structure* and marker hygiene. They do **not** verify you ran the unmarked test and watched it fail for the right reason — that stays on you. Same for per-commit lint: an installed pre-commit hook blocks dirty commits at commit time, but where no hook is installed (fresh remote environments), the after-every-commit `--all-files` run is manual discipline — do it anyway. Strict markers partially compensate (XPASS catches tests of already-existing behavior). "Lint passed" ≠ "TDD verified."

## Good tests

| Quality | Rule |
| --- | --- |
| Behavioral | Exercises a real path through the public API; survives refactors |
| Minimal | One thing. "and" in the name? Split it. |
| Clear | Name states the behavior, not `test1` |
| Honest | Tests the code, never the mock |

```ts
// Good — tests real behavior (vitest; jest: it.failing)
test.fails('retries failed operations 3 times', async () => {
  let attempts = 0;
  const op = () => { attempts++; if (attempts < 3) throw new Error('fail'); return 'ok'; };
  expect(await retryOperation(op)).toBe('ok');
  expect(attempts).toBe(3);
});
```

## Red flags — STOP, delete, restart

Unmarked test passes before implementation exists · can't explain why the test failed · weakening an assertion in GREEN to make it pass · testing the mock · "just this once" · "I'm being pragmatic, TDD is dogmatic."

Read [testing-anti-patterns.md](testing-anti-patterns.md) to avoid common pitfalls.

## Rationalization table

| Excuse | Reality |
| --- | --- |
| "Too simple to test" | Simple code breaks. The test takes 30s. |
| "I'll test after" | Tests-after are biased by the implementation: "what does this do?" not "what should this?" |
| "Deleting hours of code is wasteful" | Sunk cost. Unverified code is debt. |
| "Test is hard to write" | Hard to test = hard to use. Listen to it; simplify the interface. |
| "Must mock everything" | Too coupled. Inject dependencies. |
| "Lint passed, TDD done" | Hooks check structure, not that you watched the failure. |

## When stuck / debugging

Don't know how to test → write the wished-for API and assertion first. Found a bug → write a failing test reproducing it, then run the full protocol. Never fix a bug without a test.


[View on SkillFed](https://skillfed.io/frankify-app/skills/tdd) · [View on GitHub](https://github.com/frankify-app/skills)