diagnose
Diagnose
A discipline for hard bugs. Skip phases only when explicitly justified.
When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
Phase 1 — Build a feedback loop
This is the skill. Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.
Ways to construct one — try them in roughly this order
- Failing test at whatever seam reaches the bug — unit, integration, e2e.
- Curl / HTTP script against a running dev server.
- CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
- Headless browser script (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
- Replay a captured trace. Save a real network request / payload / event log to disk; replay it through the code path in isolation.
More from fimoklei/pm-ai-playbook
first-principles-decomposer
Break any problem down to fundamental truths, then rebuild solutions from atoms up. Use when user says "firstp", "first principles", "from scratch", "what are we assuming", "break this down", "atomic", "fundamental truth", "physics thinking", "Elon method", "bedrock", "ground up", "core problem", "strip away", or challenges assumptions about how things are done.
22idea-challenger
Pre-launch red team analysis that identifies failure modes and validates assumptions before resource commitment. Use when evaluating new products/features/strategies, before significant resource allocation, when stakeholders seem overly optimistic, or when cost of failure would be high (reputation, budget, market position).
21optimize-docs
Condense markdown documentation for token efficiency while preserving all semantic meaning. Use when rules, documentation, or config files need optimization. Target 25-40% reduction through systematic condensation patterns.
20pre-mortem-analyst
Imagine the project already failed, then work backward to find why. More powerful than risk assessment because it assumes failure is certain. Use when user says "pre-mortem", "premortem", "imagine this failed", "what could go wrong", "risk analysis", "before we launch", "stress test", "what would kill this", "project risks".
20inversion-strategist
Flip problems upside down - instead of "how to succeed", ask "how to definitely fail" then avoid those paths. Use when user says "invert", "inversion", "flip it", "opposite approach", "how would this fail", "avoid failure", "what NOT to do", "Munger", "anti-goals", "guarantee failure".
20security-threat-model
Repository-grounded threat modeling that enumerates trust boundaries, assets, attacker capabilities, abuse paths, and mitigations, and writes a concise Markdown threat model. Trigger only when the user explicitly asks to threat model a codebase or path, enumerate threats/abuse paths, or perform AppSec threat modeling.
18