Debug Investigate

How It Works

1. Why is this failing?: A bug or failure to root-cause; --continue resumes
2. Init persistent debug file: .debug/{slug}.md — immutable symptoms, append-only Eliminated log
3. Gather evidence first: Full error · codebase search · git log · tests — before any hypothesis
4. Form falsifiable hypotheses: Specific + testable; anti-bias check (confirmation · anchoring · sunk cost)
5. Test one hypothesis at a time: One experiment each; never re-test the Eliminated section
6. Fix, verify, post-mortem: Targeted test + full suite, mark resolved, write lessons.md entry
7. Resolved + elimination log: Root cause recorded; dead ends survive context resets

Invocation Triggers

Use Cases

• Investigate a production bug with a structured methodology
• Resume a debugging session across context resets without repeating dead ends
• Debug a failing CI test with systematic hypothesis elimination

The Problem

The #1 AI debugging failure isn't wrong hypotheses — it's re-testing the ones you already eliminated. Context resets, long sessions, multiple agents: without a log, you circle the same dead ends indefinitely. The scientific method works. The problem is that nothing enforces it. This skill creates a persistent debug file that makes eliminated hypotheses append-only and session-proof.

What It Does

1. 1
   Initialize the debug file

   Creates `.debug/{slug}.md` in the project root with immutable Symptoms, a Current Focus field (overwritten before every action), an append-only Eliminated section, and an Evidence Log. If `--continue` is passed, reads the existing file instead.

2. 2
   Gather evidence before forming hypotheses

   Reads the full error, searches the codebase for the exact message, reads the full function (not just the line), checks git log for recent changes, runs tests. All findings go into the Evidence Log before any hypothesis is formed.

3. 3
   Form falsifiable hypotheses

   Each hypothesis must be specific and falsifiable — "the auth token expires because the refresh logic uses < instead of <= for the expiry check", not "something is wrong with auth". Anti-bias checklist enforced: confirmation bias, anchoring, sunk cost, recency.

4. 4
   Test one hypothesis at a time

   Updates Current Focus before every action. Runs one experiment per hypothesis. CONFIRMED → fix. ELIMINATED → appended to the Eliminated section with evidence reference, then next hypothesis. Never re-tests anything in Eliminated.

5. 5
   Fix, verify, post-mortem

   Implements the fix, runs the failing test, runs the full suite. Updates the debug file to resolved. Writes a lessons.md entry with root cause, detection latency, and alerting gap. Checks if a regression test is needed.

What You Get / What It Doesn't Do

Tips

Get the Skill

Commonly Used With