What Is the Prove-It Pattern for Bug Fixes in TDD?

The Prove-It pattern is a Test-Driven Development workflow where you first write a failing test that reproduces a bug, then implement the minimal code fix to make it pass, ensuring every defect becomes a permanent regression test.

The Prove-It pattern defines the standard workflow for fixing bugs when using Test-Driven Development in the open-source addyosmani/agent-skills repository. Documented in skills/test-driven-development/SKILL.md, this systematic approach ensures that every bug fix is guarded by an automated test that prevents regression. Unlike ad-hoc debugging, the Prove-It pattern converts one-off defects into a permanent safety net.

How the Prove-It Pattern Works

The pattern consists of six distinct steps that guarantee bugs are properly captured before being fixed. According to the source code in skills/test-driven-development/SKILL.md, the workflow proceeds as follows:

1. Bug report arrives – A defect is identified by a user, tester, or monitoring tool.
2. Write a reproduction test – Create a test expressing the expected correct behavior that fails with the current implementation.
3. Confirm the failure – Run the test to verify it correctly captures the bug.
4. Implement the minimal fix – Modify production code just enough to make the test pass.
5. Verify the fix – Run the test again to confirm it now passes.
6. Run the full test suite – Ensure no regressions were introduced elsewhere.

This methodology guarantees that you prove the bug existed, fix it, and prove it no longer occurs.

Prove-It Pattern Example: Fixing a Missing Timestamp

The canonical example from skills/test-driven-development/SKILL.md demonstrates fixing a bug where completing a task fails to update the completedAt timestamp. The implementation follows the exact six-step workflow:

// Bug: "Completing a task doesn't update the completedAt timestamp"

// Step 1: Write the reproduction test (it should FAIL)
it('sets completedAt when task is completed', async () => {
  const task = await taskService.createTask({ title: 'Test' });
  const completed = await taskService.completeTask(task.id);

  expect(completed.status).toBe('completed');
  // This assertion fails with the buggy implementation
  expect(completed.completedAt).toBeInstanceOf(Date);
});

// Step 2: Fix the bug in production code
export async function completeTask(id: string): Promise<Task> {
  return db.tasks.update(id, {
    status: 'completed',
    completedAt: new Date(),   // ← added missing timestamp
  });
}

// Step 3: Run the test → it now PASSES, confirming the fix

By writing the failing test first, you create a regression test that permanently guards against this specific defect.

Adapting the Prove-It Pattern to Your Codebase

You can apply this workflow to any language or framework. Here is a minimal, self-contained illustration using a user creation service:

// Step 1: Reproduction test (fails with current buggy code)
it('adds a new user to the database', async () => {
  const user = await userService.createUser({ name: 'Alice' });
  expect(user.id).toBeDefined();          // fails if `id` is not set
  expect(user.createdAt).toBeInstanceOf(Date); // fails if timestamp missing
});

// Step 2: Bug-fix implementation (make the test pass)
export async function createUser(input: { name: string }): Promise<User> {
  const user = {
    id: generateId(),
    name: input.name,
    createdAt: new Date(),
  };
  await db.users.insert(user);
  return user;
}

// Step 3: After running `npm test`, the test now passes

This example from the agent-skills repository demonstrates turning a missing field bug into a documented behavior requirement.

Key Files in the agent-skills Repository

Understanding the Prove-It pattern requires familiarity with these specific files:

• skills/test-driven-development/SKILL.md – Defines the Prove-It pattern and provides the canonical TypeScript example for bug fixes.
• references/testing-patterns.md – Supplies additional testing patterns and assertions that support writing effective reproduction tests.

These documents collectively establish the philosophy that every bug fix must be preceded by a failing test.

Summary

• The Prove-It pattern requires writing a failing test before touching production code when fixing bugs.
• The workflow consists of six steps: report, reproduce, confirm, fix, verify, and regression test.
• According to the addyosmani/agent-skills source code, this pattern is documented in skills/test-driven-development/SKILL.md.
• Every bug fix becomes a permanent regression test that prevents the defect from reoccurring.
• The pattern applies to any programming language and integrates with existing test suites.

Frequently Asked Questions

What is the Prove-It pattern in TDD?

The Prove-It pattern is a Test-Driven Development workflow specifically designed for bug fixes where you first write a test that reproduces the bug and fails with the current code. Only after confirming the test fails do you implement the fix, ensuring the test passes afterward. This approach is formally defined in the skills/test-driven-development/SKILL.md file of the addyosmani/agent-skills repository.

How does the Prove-It pattern differ from regular TDD?

While standard TDD typically follows "write test, write code, refactor" for new features, the Prove-It pattern specifically addresses existing bugs by mandating that you prove the bug exists with a failing test before fixing it. This ensures the reproduction test remains in your suite as a regression test, whereas regular debugging might fix the issue without adding test coverage.

Where is the Prove-It pattern documented?

The Prove-It pattern is documented in the skills/test-driven-development/SKILL.md file within the addyosmani/agent-skills repository on GitHub. This file contains the formal definition, the six-step workflow, and concrete TypeScript examples demonstrating how to fix bugs like missing timestamps in task management systems.

Can I use the Prove-It pattern with existing test suites?

Yes, the Prove-It pattern integrates with existing test suites by simply adding a new reproduction test case that demonstrates the bug. As shown in the repository examples, you write the failing test using your existing testing framework and assertions, then run your full test suite after the fix to ensure no regressions occur. The pattern works with Jest, Mocha, Vitest, or any other testing framework.

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