# Tdd

> Behavior-first red-green-refactor testing. Use when building features, fixing bugs, or needing integration tests.

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

---


<skill_context>
  <skill_dir>skills/tdd</skill_dir>
  <workspace_dir>/Users/tothemoon/Dev/code-forge/knowledge-wiki-system</workspace_dir>

  <path_policy>
    Relative file references in this SKILL.md normally resolve from skill_dir when they exist there.
    Plain workspace commands like git status and bun test usually run in the workspace unless instructed otherwise.
    Use $PI_SKILL_DIR/path for explicit bundled skill files.
    Use $PI_WORKSPACE/path for explicit workspace/project files.
  </path_policy>
</skill_context>

## Wiki/Forge session context

Resolve vault via `KNOWLEDGE_VAULT_ROOT` or `wiki config --effective --repo <path>`. Do not create durable project memory markdown inside the code repo unless the repo itself is the configured vault.
Forge-tracked use: obey the active Forge phase packet, its required skills, artifact owner, and allowed writes.
Standalone use: route durable memory through Wiki under `${KNOWLEDGE_VAULT_ROOT}/projects/<project>/`.

# Test-Driven Development

## Philosophy

Tests should verify behavior through public interfaces, not implementation details.

**Good tests** are integration-style: they exercise real code paths through public APIs and describe what the system does.

Bad tests mock internals, test private methods, or break when behavior stays the same. See [tests.md](tests.md), [mocking.md](mocking.md), [interface-design.md](interface-design.md), and [deep-modules.md](deep-modules.md).

## Anti-Pattern: Horizontal Slices

DO NOT write all tests first, then all implementation.

Horizontal RED/GREEN creates tests for imagined behavior. Correct approach: Vertical slices via tracer bullets.

```
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
```

## Workflow

1. Read domain language and ADRs before naming tests.
2. Ask: "What should the public interface look like? Which behaviors are most important to test?"
3. Write one failing behavior test through the public interface.
4. Write minimal code to pass.
5. Repeat one behavior at a time.
6. Refactor only while green; Never refactor while RED.

## Checklist

- Test describes behavior, not implementation.
- Test uses public interface only.
- Test would survive internal refactor.
- No speculative features added.

## Ralph loop (fresh-context TDD)

For AFK/unattended work, use the Ralph pattern:
- **One behavior per loop iteration** — narrow scope produces better outcomes than broad scope.
- **State persists via git and tests, not context** — commit after each green, reset context if needed.
- **Tests are backpressure** — they verify non-deterministic agent output did the right thing.
- **Never batch tests** — write one test, make it pass, repeat. Horizontal slices (all tests first) test imagined behavior.
- **Specs as persistent memory** — the slice plan and acceptance criteria are re-read each iteration, not carried in context.

## Phase: implement

This skill is loaded during the **implement** phase of the Forge lifecycle.

The agent loops vertically — one behavior at a time:

1. Write a failing test (RED)
2. Record the red evidence
3. Write minimal code to pass (GREEN)
4. Record the green evidence
5. Refactor while green (never refactor while RED)
6. Commit the passing increment
7. Repeat for the next behavior

Commands per iteration:

```
wiki forge tdd red <project> <slice-id> --test <path> --command "<failing test command>"
wiki forge tdd green <project> <slice-id> --test <path> --command "<passing test command>"
```

Or the combined form:

```
wiki forge tdd cycle <project> <slice-id> --test <path> --red-command "<cmd>" --green-command "<cmd>"
```

After all behaviors are green, the phase advances to **verify**.

## Forge integration

Load this skill when the phase packet lists `tdd`.
Before changing files, ensure /wiki and /forge skills are loaded.
Record red/green with `wiki forge tdd cycle <project> <slice>`; the preferred `tdd cycle` command may use different red and green commands when they share a `--test` path.
Record targeted verification with `wiki forge evidence <project> <slice> verify`.
**After TDD completes:** return to `/forge` — run `wiki forge next` to advance.