diagnosing-bugs

Generated source view for the actual executable engineering/diagnosing-bugs skill. The durable routing article is Agent Engineering Skills. Source: skills/engineering/diagnosing-bugs/SKILL.md

Runtime Source

Bundled Resources

No bundled resource files.

Description

Disciplined diagnosis loop for hard bugs, regressions, failures, flakes, and performance problems. Use when the user says "diagnose", "debug this", "this is broken", "why is this failing/slow", or reports a bug that needs a tight repro before fixing. Adapted from mattpocock/skills.

Skill Source

---
name: diagnosing-bugs
description: Disciplined diagnosis loop for hard bugs, regressions, failures, flakes, and performance problems. Use when the user says "diagnose", "debug this", "this is broken", "why is this failing/slow", or reports a bug that needs a tight repro before fixing. Adapted from mattpocock/skills.
origin: personal
source_slug: diagnosing-bugs
---

# Diagnosing Bugs

The skill is the feedback loop. Do not jump from symptom to theory until there is a
red-capable command that exercises the user's actual bug.

## Phase 1 - Build A Tight Loop

Prefer, in order:

1. failing test at the seam that reaches the bug
2. HTTP/curl script against a running server
3. CLI invocation with fixture input and expected output
4. Playwright/browser script for UI bugs
5. replayed trace, HAR, payload, event log, or fixture
6. throwaway harness around the smallest subsystem
7. property/fuzz loop for intermittent wrong output
8. bisection or differential loop

Completion criterion:

- one command exists
- it can go red on this exact bug
- it is deterministic or has a high pinned reproduction rate
- it is fast enough to run repeatedly
- it is agent-runnable

If no loop is possible, stop and ask for a trace, log, access, or permission to add
temporary instrumentation.

## Phase 2 - Reproduce And Minimize

Run the loop. Confirm it fails for the user's symptom. Then remove inputs, config,
steps, and callers one at a time until every remaining part is load-bearing.

## Phase 3 - Hypothesize

Write 3-5 ranked hypotheses. Each must predict what would change if it were true.
Show the list briefly; proceed if the user is AFK.

## Phase 4 - Instrument

Change one variable at a time. Prefer debugger/REPL over logs. If logging, tag every
temporary line with a unique prefix and remove it before finishing.

## Phase 5 - Fix And Lock

Turn the minimized repro into a regression test when a correct seam exists. If no
correct seam exists, document that as an architecture finding and consider
`codebase-design`.

## Phase 6 - Closeout

Before declaring done:

- original repro is green
- regression test passes or missing seam is documented
- temporary instrumentation is removed
- the correct hypothesis is stated in the final notes

## Related Skills

- `tdd` when the bug can be fixed test-first.
- `counterfactual` when expected behavior needs formal comparison.
- `recent-code-bugfix` when the bug likely came from recent commits.
- `webapp-testing` for browser-visible bugs.

Upstream: `github.com/mattpocock/skills/skills/engineering/diagnosing-bugs/SKILL.md`
at `5d78bd0903420f97c791f834201e550c765699f8`.

---

Timeline

• 2026-07-15 | Generated a browseable source page from the actual executable skill file. Source: skills/engineering/diagnosing-bugs/SKILL.md