---
name: diagnose
description: >-
  Run a disciplined diagnosis loop for bugs, failures, flaky behavior, and performance regressions:
  build a red-capable loop, reproduce and minimize, rank falsifiable hypotheses, instrument, fix,
  and regression-test. Use when the user explicitly asks to diagnose or debug a problem.
license: MIT
metadata:
  original_author: Matt Pocock
  original_source: https://github.com/mattpocock/skills/tree/6acc160e4e0cd062dbbbd7a1b26ae92855edf07e/skills/engineering/diagnosing-bugs
  upstream_reviewed: 6acc160e4e0cd062dbbbd7a1b26ae92855edf07e
disable-model-invocation: true
argument-hint: "[problem]"
---

# Diagnose

Use a tight evidence loop for hard bugs. Each phase produces the evidence required by the next; skip
a phase only when current evidence explicitly satisfies its completion criterion.

Keep domain names aligned with `AGENTS.md ## Terminology` when present.

## Redact what you show

This workflow shows commands, outputs, and captured artifacts. Replace every secret with
`<REDACTED>` before showing it. Build loops against environment variables so credentials stay in the
environment rather than in the shown command. Quote from captured artifacts — HAR files, log dumps,
traces — only the lines that carry the signal; they often embed auth headers. If the redacted output
is not enough to diagnose the bug, say so and ask the user.

## 1. Build a tight red-capable loop

This is the primary work. Find the smallest credible signal that can catch this exact bug:

1. failing unit, integration, or end-to-end test;
2. HTTP, CLI, or command invocation with fixture input and asserted output;
3. headless browser assertion over DOM, console, or network behavior;
4. captured request, trace, payload, event, or data replay;
5. throwaway harness around the suspect subsystem;
6. property, fuzz, stress, bisection, or differential loop;
7. [`scripts/hitl-loop.template.sh`](scripts/hitl-loop.template.sh) only when human interaction is
   unavoidable.

Tighten the loop by reducing runtime, isolating setup, pinning time, seeding randomness, freezing
network or filesystem dependencies, and asserting the specific symptom.

For nondeterministic bugs, raise and measure the reproduction rate through repetition, concurrency,
or timing stress until the signal is useful.

Phase 1 is complete only when one command has already been run and is:

- **red-capable**: exercises the real bug path and catches the user's exact symptom;
- **deterministic**: gives the same verdict, or a pinned high reproduction rate for a flaky bug;
- **fast**: normally seconds rather than minutes;
- **agent-runnable**: unattended except through the structured HITL script.

If no credible loop can be built, stop. Report what was tried and request the missing redacted
artifact, environment, access, or permission for targeted instrumentation. Do not hypothesize
without a red-capable loop.

## 2. Reproduce and minimize

Run the loop and confirm it fails in the way the user described, not at a nearby setup error. Repeat
enough times to establish the signal.

Then remove inputs, callers, configuration, data, and steps one at a time, rerunning after every
change. Stop minimizing when every remaining element is load-bearing: removing any one makes the
loop green or changes the failure mechanism.

## 3. Rank falsifiable hypotheses

Generate three to five ranked hypotheses before probing any one. Write each as:

```text
If <cause> is true, then <one probe> will produce <observable result>.
```

Discard explanations that make no prediction. Show the ranked list to the user, then continue with
the leading safe probe without waiting for a reply.

Do not include untethered fixes in the list. A change is a probe only when its predicted observation
would confirm or falsify a cause.

## 4. Instrument one variable at a time

Map every probe to one hypothesis and change one variable at a time.

Prefer:

1. debugger or REPL inspection;
2. targeted assertions, counters, snapshots, or timing probes;
3. narrow logs at boundaries that distinguish hypotheses.

Avoid broad logging followed by grep. Tag temporary output with a unique prefix such as
`[DEBUG-a4f2]` so cleanup is checkable.

For performance regressions, establish a baseline measurement, profiler result, query plan, or
timing distribution before modifying behavior. Measure first, then bisect or probe.

Update the rankings when evidence contradicts the current theory. Do not force observations to fit
the first plausible explanation.

## 5. Lock the bug down and fix the cause

When a correct test seam exists, convert the minimized reproduction into a failing regression test
before applying the fix. The seam must exercise the actual bug pattern; a shallow test that cannot
reproduce the causal path gives false confidence.

Make the smallest change that explains both the original failure and the probe results. Rerun:

- the regression test;
- the minimized loop;
- the original, unminimized reproduction.

If the fix fails, revert or revise that attempt before testing another hypothesis. Do not stack
speculative patches. After three plausible failed fixes, stop and reassess the reproduction, system
boundary, ownership model, and test seam before attempting a fourth. Summarize what each failed
attempt proved, then ask the user about the blocking decision or recommend an explicit invocation of
`engineering:improve-codebase-architecture` when the code shape is the blocker.

When no correct regression seam exists, record that as an architecture and testability finding and
prove the fix with the best available loop.

## 6. Clean up and learn

Before declaring completion:

- rerun the original reproduction and show it is green;
- run the regression test and nearby relevant validation;
- search for and remove the unique debug prefix;
- remove throwaway harnesses and scaffolding unless deliberately retained as durable tooling;
- state the supported root cause and which evidence ruled out the alternatives;
- identify what would have prevented the bug.

If prevention requires architectural work, recommend an explicit invocation of
`engineering:improve-codebase-architecture` with the missing seam or coupling evidence. Make that
recommendation after the fix, when the system is best understood.

## Final report

End with the loop command and its before/after signal, the minimized reproduction, the fix, the
regression test, and validation results, alongside the phase 6 statements.