---
name: pwk-diagnose
description: "Disciplined debugging loop for hard bugs and performance regressions. Use when a test fails unexpectedly, a bug is found during execution, or something is broken. Use this skill whenever the user reports a bug, says 'this doesn't work', 'something's wrong', 'help me debug', or when tests fail for unclear reasons. Works at any point in the workflow — brainstorm, execute, or standalone."
---

# Diagnose

A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.

Invoking `/skill:pwk-diagnose` **exits the gated brainstorm/plan phase** (the workflow guard unlocks) — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. If you only wanted read-only investigation, use `/skill:pwk-status` (stays gated) or reinstate the lock with `/pwk-guard on`.

## Phase 1 — Build a feedback loop

Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.

Other strategies when the basics don't work:
- **Bisection** — bug appeared between two known states? Automate "boot at state X, check, repeat" to bisect
- **Replay** — save a real network request or event log to disk, replay it through the code path in isolation

The loop must produce the failure mode the **user** described — not a nearby but different failure. Iterate on the loop itself: can you make it faster? Sharper? More deterministic?

If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.

Hold at Phase 1 until you have a loop you believe in. Everything downstream — hypotheses, instrumentation, the fix — depends on that loop actually reproducing the user's symptom.

## Phase 2 — Reproduce

Run the loop. Confirm:
- The failure matches the user's reported symptom
- The failure is reproducible across multiple runs
- You've captured the exact symptom (error message, wrong output, slow timing)

Then **minimize the repro** — strip it down to the smallest input, shortest path, or fewest steps that still triggers the bug. A minimized repro dramatically narrows the hypothesis space.

## Phase 3 — Hypothesise

Generate 3-5 ranked hypotheses. Each must be falsifiable:

> "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."

Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly.

## Phase 4 — Instrument

Each probe must map to a specific hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup later. Prefer a debugger breakpoint over logs when available.

## Phase 5 — Fix + regression test

Write the regression test **before** the fix — but only if there's a correct seam (one that exercises the real bug pattern at the call site). If no correct seam exists, note it — the codebase architecture is preventing the bug from being locked down.

## Phase 6 — Cleanup

Required before declaring done:
- Original repro no longer triggers
- Regression test passes (or absence of seam is documented)
- All `[DEBUG-...]` instrumentation removed
- Ask: what would have prevented this bug?
- If the answer is a repeatable pattern, append a **generic** rule to `docs/lessons.md` (strip domain specifics) so future sessions catch it early.
- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/adr/` capturing that insight
