Ask an AI agent to fix a bug with no process wrapped around it, and you'll typically get a fix — fast, confident, and sometimes completely unrelated to what actually broke. The Investigate skill exists to interrupt that reflex.
Step one: restate the symptom precisely
Before anything else, the skill restates what was actually reported — what the user observes, when, under what conditions. This sounds trivial, but a huge fraction of debugging time gets wasted chasing a slightly-wrong version of the actual problem. Getting the symptom description exactly right is cheap insurance against that.
Step two: follow the evidence, not the first theory
Next, the codebase gets searched, relevant code paths read, logs and state checked as needed — following evidence rather than the first plausible-sounding theory. Critically, when a workflow's actual outcome is in doubt, it gets verified by running it or querying real state, not just reasoned about from reading code. An agent that only ever reasons from source code will confidently describe behavior the code doesn't actually produce.
Step three: cite the cause, don't just name it
The root cause gets cited to specific files and lines — not "somewhere in the auth logic," but the actual function and line number. If there are multiple contributing causes, all of them get listed, not just the first one found. When the cause is a chain of interacting steps, the finding includes a Mermaid diagram rather than a paragraph trying to describe a sequence in prose.
Why this is a separate step, not a preamble to the fix
The discipline that matters isn't the document — it's the refusal to let "propose a fix" and "find the cause" happen in the same breath. Separating them means the fix, when it comes, is scoped against something real: a cited cause you've confirmed, not a plausible guess that happened to compile. It also means the investigation and the fix live in separate places — ./investigations/ versus ./spec/ — because a diagnosis and a specification of work to build are genuinely different documents, even when they're about the same bug.
Next time something breaks and the cause isn't already obvious, resist the pull toward a quick patch. Ask for the cause first. It's a five-minute habit that saves the hour you'd otherwise spend re-fixing the same bug a second time.