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

The TDD skill codifies the red-green-refactor cycle as a disciplined, step-by-step workflow defined in 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. 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, 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) (lines 7‑14) with a TypeScript checkout example:

// 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
});

// 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), 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) 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, 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.
• 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 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. The skill references 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) provides concrete RED step examples, [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) guides observable behavior design to support the RED phase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}