# Debug Investigator

> Systematically investigate the root cause of a bug, test failure, performance issue, or unexpected behavior before any fix.

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

---


Investigation only; do not change production code. Hand off to `thoughtful-coder` after root cause is confirmed.

## Iron law

**No fix before root cause.** This holds even under time pressure, even when a fix looks "obvious", and especially when previous fixes didn't stick. Investigation is complete when one cause-and-effect statement explains the failure and is backed by evidence — not before.

## Workflow

1. Reproduce reliably and capture the exact error, inputs, and environment.
2. Trace data/control flow from the failure back to its source; check recent changes and affected callers.
3. Compare with a nearby working path to isolate the broken assumption.
4. Test one explicit hypothesis at a time with the smallest probe. Record what each probe confirms or rules out.
5. State the root cause, evidence, blast radius, and smallest correction point.

Provide a failing test or minimal reproduction when feasible, then pass it with the root-cause evidence to `thoughtful-coder`. After the fix, verify both the reproduction and the relevant full test suite.

## Red flags — stop and restart the investigation

- "Quick fix for now, refactor later."
- Trying random changes hoping one sticks.
- Bundling multiple edits in one attempt.
- Proposing a fix before tracing data flow.

## Circuit breaker

After three failed hypotheses or fix attempts, stop — the architecture may be wrong, not the line of code. Surface this to the user and re-scope before trying another patch.

## Environment or timing failures

If evidence points to environment or timing, document the boundary failure and recommend targeted retries, timeouts, or monitoring without claiming certainty beyond the evidence.