---
type: skill
name: investigate
description: a defect whose cause is unknown, a fix that did not hold, a test that fails only sometimes, an incident that needs a cause before a patch
sources:
  - obra/superpowers — systematic-debugging (MIT)
  - gstack — investigate (MIT)
standing: draft
owner: "{{owner}}"
updated: "{{date}}"
---

# Skill — investigate

_Invoke in any agent conversation with `/investigate` when something is broken and nobody can yet
say why. The discipline is root cause before repair: reproduce it, table the possible causes, prove
one, and only then change code. The steps are a starting opinion; edit them until they read the way
this company debugs._

**The Iron Law.** No fix before a reproduced defect. A patch written before the cause is proven is
a bet, and every symptom-level bet makes the next defect harder to find because the evidence is now
buried under the patch. When the law collides with urgency, the law wins — the fastest route to a
fix that holds runs through the reproduction.

**Step 1: reproduce.** Get the defect to happen on demand, and quote the proof: the exact command,
the failing output, the line it points at. Read the code path from the symptom backwards, and read
the recent history of the affected files (`git log` over them) — a regression's cause is usually in
the diff. If you cannot reproduce it, say so and stop: the deliverable becomes instrumentation and
better evidence — a log line at the suspected seam, a tightened assertion — never a patch. An
intermittent defect is reproduced when its trigger is, not when it happens to appear.

**Step 2: the hypothesis table.** Every plausible cause gets a row, and a row is honest only with
every column filled:

| Hypothesis | Evidence for | What would kill it | Status |
| --- | --- | --- | --- |
| a testable claim about cause | quoted output, never memory | the cheapest ruling observation | open |

Test the cheapest discriminating observation first — one log line placed at the fork between two
hypotheses beats an hour of reading. A hypothesis with no kill condition is a belief, and it does
not get a row until it has one. Mark rows dead with the observation that killed them; a dead row is
evidence too, and deleting it hides the search from the next reader.

**Step 3: the fix.** The fix follows the proven cause only: the smallest change that removes it,
with no adjacent refactors riding along. It ships with the regression test that captures the
reproduction — red first, so the test fails without the fix and passes with it — and closes with
fresh verification: the Step 1 reproduction run again, quoted, passing. "This should fix it" is not
a sentence this skill ends on.

**Three failed fixes.** Stop patching and question the architecture. A defect that survives three
proven-cause fixes, or keeps recurring in the same files, is not a defect in a line — it is a
defect in a structure, and the honest output is that finding, written up with the dead hypotheses
attached, not a fourth patch.

**The rationalization table.** The excuses are known in advance, so they are answered in advance:

| The excuse | The answer |
| --- | --- |
| "it's obvious what's wrong" | obvious is a hypothesis — give it a row and a kill condition |
| "we're in a hurry" | the slow path is a fix on the wrong cause, and coming back later |
| "just add a guard for now" | a guard that hides the cause is the same defect, now quieter |
| "it works now" | show it failing before and passing after, or nothing is known |

**Where the output lands.** An investigation reads canon before it writes anything: the engineering
department's standards are part of the evidence, and a fix that violates them is not done. The fix
lands as an ordinary diff through review; anything gated — canon, standards, policy — goes through
`overbot propose`, never a direct write. What the incident should teach the company is the
postmortem skill's document, written after the fix holds; this skill's record is the table and the
proof.

**The refusal.** Asked to skip the reproduction and ship the patch — "we already know what's
wrong, just fix it" — this skill refuses the speculative patch and says why: a fix with no
reproduced defect is a guess wearing a diff. Nobody can say whether it worked, because nothing was
ever seen failing. The refusal comes with the smallest next move: the one command or log line that
would turn the guess into a row in the table.

type: skill
name: investigate
about: "Root cause before repair: reproduce the defect, list the possible causes, prove one, and only then change code. Use it when something is broken and nobody can yet say why."
version: "0.1.0"