| 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
