# Investigate

> Use when something is broken and you don't yet know why — drives a hypothesis-led investigation that builds a minimum repro, eliminates variables, and isolates the root cause. Reach for it for "why is this failing?" before attempting a fix.

- Skill: `jokerman89/investigate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jokerman89/investigate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/investigate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jokerman89/investigate

---


# /investigate

The debugging skill. Hypothesis-first, scientific-method approach: state what you observe, propose hypotheses, design a minimum repro, eliminate variables one at a time, name the root cause. No speculation, no guess-fix-rerun loops.

Distinct from `/qa --no-fix`: that one runs the suite and reports. This one zooms in on a single failure or anomaly and drives it to root cause.

## When to use

- A test is failing and `/qa` flagged it as product-logic
- Production logs show an anomaly and you need to understand why
- A user-reported bug needs root-cause analysis before a fix design
- A flake is recurring — investigate whether it's actually flake or a real race

## When NOT to use

- The fix is obvious and trivial — just fix it
- You haven't reproduced the issue yet AND can't — use `/qa-only` first to confirm it's real
- It's a UX issue, not a correctness issue — use `/design-review` or `/qa` with browser

## Inputs

- A failure description, error message, log excerpt, or test name (passed inline or via the latest `/qa-only` report)
- Optional `--scope <file>` — narrow code reading to a specific area
- Optional `--with-codex` — invoke `/codex` mid-investigation for an outside opinion on the hypothesis set

## Workflow

1. **State the observation precisely.** What's the failure? Exact error, exact assertion, exact log line. No paraphrasing.
2. **Minimum repro.** Smallest possible command/test/script that triggers the failure. If you can't reduce it: surface that as a finding.
3. **Hypothesis set.** Generate 3-5 candidate explanations. Rank by probability. Include "no idea yet" if honest.
4. **Variable isolation.** For each hypothesis, design ONE experiment that distinguishes it. Run it. Update the ranking.
5. **Iterate.** Hypotheses survive or fall. New ones spawn from the experiments. Continue until one hypothesis is confirmed via direct evidence (not just elimination).
6. **Root cause statement.** A single sentence: "X happens because Y, observable at Z." Cite file:line.
7. **Fix recommendation.** NOT a fix. A recommendation — operator decides whether to fix here, escalate, or punt.

## Report format

```
Investigation: <one-line failure description>

## Observation
Exact error: <verbatim>
Repro: <minimum command>
First seen: <commit or timestamp>

## Hypotheses (initial)
H1: <hypothesis> — probability: 0.5
H2: <hypothesis> — probability: 0.3
H3: <hypothesis> — probability: 0.2

## Experiments
[E1] Test H1 by <action>. Result: <observation>. Updates: H1 → 0.1, H2 → 0.7
[E2] Test H2 by <action>. Result: <observation>. CONFIRMED.

## Root cause
src/lib/dlxClient.ts:87 — fetch retries don't reset the AbortController, so the second attempt cancels itself.

## Fix recommendation
Minimal fix: reset controller in the retry path (5-line change).
Risk: low. No callers depend on the canceled-second-attempt behavior.
Recommend: fix here, add regression test.
```

## Compliance integration

- Read-only mode. No code mutation in this skill. If investigation reveals a sec-issue (e.g. token in logs): surface as Layer 2 sanitization concern, do NOT fix in this skill.
- If repro requires customer-data: STOP. Use synthetic data, or escalate to operator for sanitized fixture.

## Failure modes

- **Cannot reproduce:** name that as a finding. "Cannot reproduce in 50 attempts under conditions X, Y, Z" is data, not failure.
- **No hypotheses survive after N experiments:** generate a new hypothesis set. If still stuck: write up what's been ruled out, escalate to operator with `/codex` for outside opinion.
- **Repro requires production access:** stop, escalate. Per Layer 2: production reads require explicit auth.

## Examples

**Quick win:**
```
> /investigate "refund returns 200 instead of 100"
Observation: tests/billing/test_refund.py:42
Repro: pytest tests/billing/test_refund.py::test_partial_refund -x
H1: amount doubled in serialization (0.6)
H2: refund handler called twice (0.3)
H3: test fixture wrong (0.1)
[E1] Add print at serialize: amount=100 going in, 200 coming out.
ROOT CAUSE: src/lib/billing.ts:34 — `* 2` left over from a debug session.
```

**Stuck:**
```
> /investigate "auth flake in CI only"
After 4 experiments: cannot distinguish race vs. network.
Recommendation: enable CI artifact capture (har/trace) on next run, re-investigate.
```

## See also

- `/qa` — when fix is auto-applicable
- `/codex` — for outside-voice hypothesis review
- `/careful` — wrap investigation in extra rigor for prod-impact bugs
- `DebugForensics` subagent — for parallel deeper trace analysis