# Phx Investigate

> Investigate bugs and errors in Elixir/Phoenix — root-cause analysis for crashes, exceptions, stack traces, test failures. Use --parallel for deep 4-track investigation.

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

---


# 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

1. **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
2. **Check the obvious before going deep** — Compile errors, missing migrations, atom/string mismatches explain 80% of bugs; exhausting the Ralph Wiggum checklist saves hours
3. **Check changeset errors before UI debugging** — Silent form saves are almost always `{:error, changeset}` with validation failures, not viewport or JS issues
4. **Consult compound docs before investigating fresh** — A previously solved problem saves the entire investigation cycle; always search `.claude/solutions/` first
5. **NEVER guess at a fix before reproducing** — Reproduce first, then identify root cause, then fix. Skipping steps causes wrong fixes
6. **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:

1. `mcp__tidewave__get_logs level: :error` -- capture recent errors
2. Parse stacktraces, correlate with source via
   `mcp__tidewave__get_source_location`
3. For data bugs: `mcp__tidewave__execute_sql_query` to inspect state
4. For logic bugs: `mcp__tidewave__project_eval` to test hypotheses
5. 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 `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.

### Step 7: Hand Off

Present root cause + evidence. Then route by fix size:

- Small, contained fix → offer to apply directly or via `phx-quick`
- Multi-file or risky fix → suggest `phx-plan {root cause summary}` so
  the fix gets task structure and review
- Non-obvious root cause → after the fix lands, suggest `phx-compound`

## Autonomous Iteration

Use `/ralph-loop:ralph-loop` for autonomous debugging with
clear completion criteria and `--max-iterations`.

## References

- `references/error-patterns.md` — Common errors and checklist
- `references/investigation-template.md` — Output format
- `references/debug-commands.md` — Debug commands and common fixes