investigate

name	investigate
description	Systematic root-cause debugging — no fixes before root cause is confirmed
version	0.1.0
level	3
triggers	["investigate","root cause","find out why","dig into this bug","/investigate"]
context_files	["context/project.md","context/learnings.md"]
steps	[{"name":"Gather","description":"Read affected code, check recent git log, reproduce the bug deterministically, state the symptom precisely"},{"name":"Analyze","description":"Match against known bug patterns — race condition, nil propagation, state corruption, integration failure, config drift, stale cache"},{"name":"Hypothesize","description":"Rank by likelihood, confirm each with evidence; circuit-break after 3 failed hypotheses"},{"name":"Implement","description":"Fix only the confirmed root cause, minimize diff, write a regression test"},{"name":"Verify","description":"Reproduce original scenario, run full test suite, report with status verdict"}]

Investigate Skill

A structured five-phase root-cause debugging protocol. No fix is applied until the root cause is confirmed with evidence. Think of it as a controlled demolition: you do not swing the wrecking ball until you know exactly which wall to hit.

What Claude Gets Wrong Without This Skill

Without a structured protocol, debugging becomes symptom-chasing. A timeout gets wrapped in a retry loop. A nil pointer gets a nil check. The behavior stops manifesting, but the cause is still there, waiting for the next context to trigger it.

The other failure mode is hypothesis overload: generating six possible causes, trying one, giving up, trying another, losing track of what was tested. Three failed hypotheses with no circuit breaker become ten, and ten become a refactor of the wrong system.

This skill enforces gather-before-hypothesize, evidence-before-fix, and a hard stop after three failures.

Phase 1: Gather

Before forming any hypothesis:

1. Read the affected code
2. Run git log -10 --oneline to surface recent changes in the area
3. Reproduce the bug deterministically: if you cannot reproduce it, you cannot verify the fix
4. State the symptom precisely in one sentence: what happens, where, under what conditions

Do not move to Phase 2 until you can reproduce the bug or have a documented reason why reproduction is not possible.

Phase 2: Analyze

Map the symptom against known bug pattern categories. List every candidate, do not filter yet:

Pattern	What to look for
Race condition	Concurrent access to shared state, missing locks, async ordering assumptions
Nil/null propagation	Value expected to exist, flows through multiple layers before crash
State corruption	Object modified by multiple code paths, invariants violated
Integration failure	External service behavior changed, API contract drift, timeout assumptions
Configuration drift	Works in one environment, fails in another; env vars, feature flags
Stale cache	Cached value no longer valid, cache invalidation missing or incorrect

Phase 3: Hypothesize

Rank the candidates from Phase 2 by likelihood. For each, state what evidence would confirm or refute it: a failing test, a specific log line, a traced execution path.

Test them in order. For each:

• State the hypothesis
• State what evidence you expect to find