| name | phx:investigate |
| description | Investigate bugs and errors in Elixir/Phoenix — root-cause analysis for crashes, exceptions, stack traces, test failures. Use --parallel for deep 4-track investigation. |
| effort | high |
| argument-hint | <bug description> [--parallel] |
Investigate Bug
Investigate bugs using the Ralph Wiggum approach: check the
obvious, read errors literally.
Usage
/phx:investigate Users can't log in after password reset
/phx:investigate FunctionClauseError in UserController.show
/phx:investigate Complex auth bug --parallel
Arguments
$ARGUMENTS = Bug description or error message. Add --parallel
for deep 4-track investigation.
Mode Selection
Use parallel mode (spawn deep-bug-investigator) when:
bug mentions 3+ modules, spans multiple contexts, is intermittent
or involves concurrency, or user says --parallel/deep.
Otherwise: Run the sequential workflow below.
Avoid confirmatory subagents: Do NOT spawn parallel subagents
to "verify" findings you already identified in the main context.
If Step 3-4 already identified the root cause with high confidence,
present it directly — don't spend ~80K tokens on 4 subagents to
confirm what's already obvious (confirmed waste: session c135330a).
Iron Laws
- Read the error message literally first — Most bugs tell you exactly what's wrong; resist the urge to theorize before reading what the system is saying
- Check the obvious before going deep — Compile errors, missing migrations, atom/string mismatches explain 80% of bugs; exhausting the Ralph Wiggum checklist saves hours
- Check changeset errors before UI debugging — Silent form saves are almost always
{:error, changeset} with validation failures, not viewport or JS issues
- Consult compound docs before investigating fresh — A previously solved problem saves the entire investigation cycle; always search
.claude/solutions/ first
- NEVER guess at a fix before reproducing — Reproduce first, then identify root cause, then fix. Skipping steps causes wrong fixes
- DO NOT apply a fix without confirming root cause — Verify your hypothesis with evidence (logs, tests, IO.inspect) before changing code
Investigation Workflow
Step 0: Consult Compound Docs
Search .claude/solutions/ for relevant keywords using Grep.
If matching solution exists, present it and ask: "Apply this
fix, or investigate fresh?"
Step 0a: Runtime Auto-Capture (Tidewave -- PRIMARY when available)
If Tidewave MCP is detected, start here instead of asking
the user to paste errors. Auto-capture runtime context:
mcp__tidewave__get_logs level: :error -- capture recent errors- Parse stacktraces, correlate with source via
mcp__tidewave__get_source_location
- For data bugs:
mcp__tidewave__execute_sql_query to inspect state
- For logic bugs:
mcp__tidewave__project_eval to test hypotheses
- For UI bugs:
mcp__tidewave__get_source_location with component name
Present pre-populated context to the user:
Auto-captured from runtime:
- Error: {parsed error from logs}
- Location: {file:line from get_source_location}
Investigating this. Correct if wrong.
This eliminates copy-pasting errors between app and agent.
If Tidewave NOT available: Fall through to Step 1.
Step 1: Sanity Checks
Run mix compile --warnings-as-errors 2>&1 | head -50, then mix ecto.migrate.
Step 2: Reproduce
Run mix test test/path_test.exs --trace. Then read the last 200 lines of log/dev.log and search for "error" or "exception" patterns.
Step 3: Read Error LITERALLY
Parse the error message — check ${CLAUDE_SKILL_DIR}/references/error-patterns.md.
Step 4: Check the Obvious (Ralph Wiggum Checklist)
File saved? Atom vs string? Data preloaded? Pattern match
correct? Nil? Return value? Server restarted?
LiveView form saves silently failing? Check changeset errors
FIRST — not viewport, click mechanics, or JS. A missing
hidden_input for a required embedded field causes {:error, changeset} with no visible UI feedback.
Step 5: IO.inspect / Tidewave project_eval
Step 6: Identify Root Cause
Find what's actually happening vs what should happen.
Autonomous Iteration
Use /ralph-loop:ralph-loop for autonomous debugging with
clear completion criteria and --max-iterations.
References
${CLAUDE_SKILL_DIR}/references/error-patterns.md — Common errors and checklist${CLAUDE_SKILL_DIR}/references/investigation-template.md — Output format${CLAUDE_SKILL_DIR}/references/debug-commands.md — Debug commands and common fixes
