Why Agents Guess Bugs and How Two Matt Pocock Skills Keep Debugging on Track

This article analyses two skills from the mattpocock/skills repository— /tdd and /diagnosing-bugs —and explains why AI agents often guess a bug’s root cause instead of reproducing it first.

The repository classifies agent failure modes into four categories; the third category, “The Code Doesn’t Work”, is addressed by the two skills. Their core argument is that Test‑Driven Development (TDD) is not about writing many tests but about giving the agent a fast, accurate, reproducible feedback signal, while /diagnosing-bugs splits the entire debugging workflow into six mandatory phases.

Feedback loop principle : “The rate of feedback is your speed limit” (quoted from The Pragmatic Programmer ). A red‑capable command must (1) assert the exact symptom, (2) be deterministic, (3) run in seconds, and (4) be runnable by the agent without human intervention. Only when such a command succeeds does the agent move to Phase 2 (reproduce + minimise) and Phase 3 (hypothesise).

Concrete example : a fabricated login‑page white‑screen issue. The article shows a minimal Playwright script that launches the dev server, runs the test, and asserts that the page body is not empty and does not have a white background. This script satisfies the four red‑capable criteria and serves as the entry point for Phase 1.

# 1. Start a dev server
npm run dev &

# 2. Reproduce with Playwright
npx playwright test e2e/login.spec.ts --reporter=list

The six phases are:

Phase 1 – Build a feedback loop (run a red‑capable command).

Phase 2 – Reproduce and minimise the failure.

Phase 3 – Generate 3‑5 falsifiable hypotheses.

Phase 4 – Design probes that can confirm or refute each hypothesis.

Phase 5 – Fix the bug and add a regression test at the correct seam.

Phase 6 – Cleanup logs and write a post‑mortem.

Hypotheses must be expressed as “If X is the cause, changing Y will make the bug disappear”, and each hypothesis must be testable with a small code change or a logged probe. The article also stresses that a missing “correct seam” for a regression test is itself a finding, indicating untestable code.

/tdd skill : defined as the “red → green loop”. It emphasizes writing a failing test that asserts a public interface (the seam) and then implementing the minimal code to make it pass. The skill distinguishes between valuable tests (those that assert public behaviour) and anti‑patterns such as testing internal implementation details or using tautological assertions.

Key concepts include:

Public interface vs. seam – the observable boundary where behaviour is asserted.

Pre‑agreed seam – a list of interfaces agreed upon before writing tests to avoid testing implementation details.

Tracer bullet – a vertical slice (one test + minimal implementation) used to validate the path before proceeding.

Mocking principle – only mock at system boundaries (external APIs, databases, time, filesystem); never mock your own classes.

The article compares /tdd and /diagnosing-bugs: /tdd is suited for building new features when the desired behaviour is known. /diagnosing-bugs is suited for unknown failures where the symptom is known but the cause is not.

Both share the need for an explicit feedback signal, but their loops differ: /tdd uses a red‑green cycle per vertical slice, while /diagnosing-bugs follows a linear six‑phase process.

The article also lists common misuses (e.g., tests that never run, tautological tests, testing implementation details, horizontal slicing) and clarifies the limits of the two skills: they do not guarantee architectural quality, lack public ROI data, and are not official Anthropic standards.

Finally, the author provides minimal templates for issue/PR descriptions that embed the required feedback information, ensuring the agent follows the disciplined workflow.