# How the TDD Skill Implements the Red-Green-Refactor Loop in mattpocock/skills

> Discover how the TDD skill in mattpocock/skills enforces the red-green-refactor loop. Learn about its disciplined workflow for efficient, minimal code development.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: deep-dive
- Published: 2026-04-04

---

**The TDD skill codifies the red-green-refactor cycle as a disciplined, step-by-step workflow defined in [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md), enforcing a tracer-bullet approach that mandates one failing test and minimal passing code per cycle.**

The TDD skill in the mattpocock/skills repository provides a declarative implementation of classic test-driven development. Unlike generic advice, this skill structures the red-green-refactor loop as a repeatable narrative with explicit guardrails, mandatory checklists, and concrete code examples that guide AI assistants through each phase.

## Planning Phase: Observable Behavior Before Code

Before writing any tests, the skill forces a **planning checklist** defined in lines 45‑55 of [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md). This phase requires identifying the public interface and specific behaviors to test, ensuring that subsequent RED steps target observable outcomes rather than internal implementation details. The planning stage acts as a contract that prevents speculative design and keeps the loop focused on verifiable requirements.

## The Tracer Bullet: Red → Green

The core of the skill is the **tracer bullet** pattern—a minimal vertical slice that validates the testing pipeline. According to lines 62‑67 in [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md), the workflow strictly separates the RED and GREEN steps:

- **RED**: Write one failing test that defines the first behavior (line 62‑66)
- **GREEN**: Write the minimal code necessary to make that specific test pass (line 66‑67)

This is illustrated concretely in [[`tdd/tests.md`](https://github.com/mattpocock/skills/blob/main/tdd/tests.md)](https://github.com/mattpocock/skills/blob/main/tdd/tests.md) (lines 7‑14) with a TypeScript checkout example:

```typescript
// RED: failing test (tdd/tests.md)
test("user can checkout with valid cart", async () => {
  const cart = createCart();
  cart.add(product);
  const result = await checkout(cart, paymentMethod);
  expect(result.status).toBe("confirmed"); // <-- fails until checkout is implemented
});

```

```typescript
// GREEN: minimal implementation to satisfy the test
export async function checkout(cart, paymentMethod) {
  // simple, just enough to pass the test
  return { status: "confirmed" };
}

```

## Incremental Loop: One Test at a Time

For each additional behavior, the skill repeats the RED → GREEN cycle (lines 73‑78). The rules enforce strict vertical iteration:

- **One test at a time** (line 82)
- **Only enough code** to satisfy the current test (line 84)
- **No speculative code** or future-proofing (line 85)

This structure explicitly prevents the **"horizontal slice"** anti-pattern (described in lines 18‑30), where developers attempt to write all tests upfront or build infrastructure before verifying behavior. By iterating vertically—test first, then implementation—each cycle builds on a freshly verified codebase.

## Refactor Phase: Clean Only When Green

Once all planned behaviors have passing tests, the skill transitions to the **REFACTOR** stage (lines 87‑95). This phase references [[`tdd/refactoring.md`](https://github.com/mattpocock/skills/blob/main/tdd/refactoring.md)](https://github.com/mattpocock/skills/blob/main/tdd/refactoring.md), which lists specific candidates like duplication, long methods, and shallow modules. Crucially, the skill mandates that refactoring occurs **only after the entire suite is green**, ensuring that structural improvements never regress existing behavior.

## Checklist Guardrails and Anti-Patterns

Each cycle concludes with a validation checklist (lines 100‑107) that confirms:
- Test quality and specificity
- Code minimality 
- Absence of premature features

These guardrails ensure the loop remains disciplined. The skill also references [[`tdd/interface-design.md`](https://github.com/mattpocock/skills/blob/main/tdd/interface-design.md)](https://github.com/mattpocock/skills/blob/main/tdd/interface-design.md) to reinforce that RED steps should drive observable public interfaces, not internal constructs.

## Summary

- The **TDD skill** implements red-green-refactor as a structured narrative in [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md), not merely as conceptual advice.
- The **tracer bullet** approach mandates writing one failing test and minimal passing code before moving forward.
- **Vertical iteration** prevents horizontal-slice anti-patterns by enforcing one-test-at-a-time development (lines 82‑85).
- **Refactoring** is strictly gated behind a green test suite and guided by [`tdd/refactoring.md`](https://github.com/mattpocock/skills/blob/main/tdd/refactoring.md).
- **Mandatory checklists** at each phase ensure adherence to TDD principles and prevent speculative coding.

## Frequently Asked Questions

### What is the "tracer bullet" approach in the TDD skill?

The tracer bullet is a pattern defined in lines 62‑67 of [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md) that requires writing a single failing test followed by the minimal production code needed to pass it. This validates the testing infrastructure and establishes a working vertical slice before adding complexity, ensuring the RED and GREEN phases remain distinct and minimal.

### How does the skill prevent the "horizontal slice" anti-pattern?

The skill explicitly prohibits horizontal slicing—writing all tests upfront or building infrastructure before verifying behavior—through rules in lines 82‑85 that mandate **one test at a time** and **no speculative code**. Lines 18‑30 describe this anti-pattern as a workflow that defeats the feedback loop TDD is meant to provide.

### When can refactoring occur according to the skill definition?

Refactoring can only occur after **all** planned behaviors have green tests, as specified in lines 87‑95 of [`tdd/SKILL.md`](https://github.com/mattpocock/skills/blob/main/tdd/SKILL.md). The skill references [`tdiv/refactoring.md`](https://github.com/mattpocock/skills/blob/main/tdiv/refactoring.md) for specific refactoring candidates and treats the green test suite as a safety net that prevents behavior regression during structural cleanup.

### What supporting files define the TDD workflow besides SKILL.md?

The implementation relies on three supporting documents: [[`tdd/tests.md`](https://github.com/mattpocock/skills/blob/main/tdd/tests.md)](https://github.com/mattpocock/skills/blob/main/tdd/tests.md) provides concrete RED step examples, [[`tdd/refactoring.md`](https://github.com/mattpocock/skills/blob/main/tdd/refactoring.md)](https://github.com/mattpocock/skills/blob/main/tdd/refactoring.md) lists REFACTOR candidates, and [[`tdd/interface-design.md`](https://github.com/mattpocock/skills/blob/main/tdd/interface-design.md)](https://github.com/mattpocock/skills/blob/main/tdd/interface-design.md) guides observable behavior design to support the RED phase.