# Building Tdd

> Use red-green-refactor for a feature or bug fix when the user asks for test-first work.

- Skill: `socketdev/building-tdd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add socketdev/building-tdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/socketdev/building-tdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: socketdev (https://skillmd.com/u/socketdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/socketdev/building-tdd

---


# building-tdd

Red-green-refactor in **vertical slices** — one test → one implementation →
repeat. The loop is `pnpm test <file>` going red then green. Seam doctrine
(public interface, highest seam, vitest, no source-text assertions, member
co-location vs wheelhouse `test/repo/`):
[`test-layout`](../../../../docs/agents.md/fleet/test-layout.md). The deterministic
core is every `pnpm test` / `pnpm run check` run; AI owns the residue — what to
test and how to name the behaviour ([`code-first-then-ai`](../../../rules/fleet/code-first-then-ai.md)).

## Never: horizontal slices

Do NOT write all tests then all implementation. Tests written in bulk verify
_imagined_ behaviour — they assert the _shape_ of data and signatures, pass when
behaviour breaks, and outrun your understanding. One behaviour at a time.

## 1. Plan

Establish the project's behavioural vocabulary first — `rg 'describe\(' test/ |
head -20` to see how existing tests name behaviour, so your test names match.
Then list the behaviours to test (not implementation steps) and the public
interface under test. You can't test everything — pick the critical paths.

## 2. Tracer bullet

Write ONE test for ONE behaviour at the correct seam. Name the
`pnpm test <file>` invocation. Watch it go **red**. Write the minimal code to
make it green. This proves the path end-to-end.

## 3. Incremental loop

For each remaining behaviour: RED (`pnpm test <file>` fails) → GREEN (minimal
code passes). One test at a time, only enough code to pass the current test,
don't anticipate future tests, assert observable behaviour through the public
interface — never internal structure or source text.

## 4. Refactor

Only after all tests pass. Run `pnpm run check` + `pnpm run lint`. Refactor with
the green suite as your safety net; the tests shouldn't change (they verify
behaviour, not implementation). `prefer-vitest-guard` and `no-test-in-scripts-guard`
enforce the structural rules — this skill is the procedural loop they assume.

## Completion criterion

Every chosen behaviour has a passing test that exercises it through the public
interface, `pnpm run check` is green, and no test asserts implementation detail.

## Handoffs

Use [writing-fast-tests](../writing-fast-tests/SKILL.md) to pick the cheapest seam
for each test you add — the unit tier is budgeted under a minute, and a spawned
child costs ~68,000× an in-process call. Then
[reviewing-code](../reviewing-code/SKILL.md) for an independent branch review,
and [pushing](../pushing/SKILL.md) for the complete release gate.