| name | investigate |
| description | Systematic debugging skill. Use when encountering a bug, test failure, unexpected behavior, or when asked to "investigate", "debug", "diagnose", or "figure out why". Enforces root-cause-first discipline with structured hypothesis tracking. |
Investigate
Systematic debugging workflow. Do not guess-and-fix — find the root cause first.
Phase 1: Collect
Gather all available evidence before forming any hypothesis.
- Read the error message, stack trace, or symptom description exactly as given
- Identify the affected code path — read the relevant source files
- Check
git log --oneline -20 in the affected area for recent changes
- If reproducible, reproduce the issue and capture the exact output
- List what you know and what you do not know
Deliverable: a structured symptom summary with affected files, error output, and recent changes.
Phase 2: Hypothesize
Form up to 3 ranked hypotheses. For each:
- State the hypothesis in one sentence
- Identify the single cheapest check that would confirm or refute it
- Do NOT start fixing yet
Phase 3: Verify
Test hypotheses in rank order. For each:
- Run the cheapest check identified in Phase 2
- If confirmed — move to Phase 4
- If refuted — record what you learned and move to the next hypothesis
3-strike rule: If all 3 hypotheses fail, step back and re-collect. Do not keep
guessing. Re-read the code path more carefully, expand the search area, or check
for environmental factors (config, dependencies, platform).
Phase 4: Fix
Only after root cause is confirmed:
- Write the minimal fix that addresses the root cause
- Do not refactor surrounding code
- Do not add speculative defensive checks
- Run the test suite to verify the fix and check for regressions
Phase 5: Verify and Report
- Confirm the original symptom is resolved
- Confirm no regressions were introduced
- Summarize: root cause, fix applied, evidence of resolution
Rules
- Never skip Phase 1-3 and jump to fixing
- Never change tests to match broken behavior
- If the bug is in a dependency or environment, report it — do not patch around it silently
- If you cannot reproduce the issue, say so and explain what you tried
