{"slug":"investigate-5","title":"investigate","summary":"Find the root cause of Elixir/Phoenix bugs — crashes, exceptions, stack traces, compile errors, LiveView that won't update, silent failures. Use when something is broken or misbehaves. --parallel for 4 tracks.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-04T15:14:13.979532Z","repo":{"url":"https://github.com/oliver-kriska/claude-elixir-phoenix","stars":560,"forks":44,"license":"MIT","updatedAt":"2026-10-02T04:11:38Z"},"bodyHtml":"
\n

name: investigate\ndescription: \"Find the root cause of Elixir/Phoenix bugs — crashes, exceptions, stack traces, compile errors, LiveView that won't update, silent failures. Use when something is broken or misbehaves. --parallel for 4 tracks.\"\neffort: high\nargument-hint:

\n

Investigate Bug

\n

Investigate bugs using the Ralph Wiggum approach: check the\nobvious, read errors literally.

\n

Usage

\n
/phx:investigate Users can't log in after password reset\n/phx:investigate FunctionClauseError in UserController.show\n/phx:investigate Complex auth bug --parallel\n
\n

Arguments

\n

$ARGUMENTS = Bug description or error message. Add --parallel\nfor deep 4-track investigation.

\n

Mode Selection

\n

Use parallel mode (spawn deep-bug-investigator) when:\nbug mentions 3+ modules, spans multiple contexts, is intermittent\nor involves concurrency, or user says --parallel/deep.

\n

Before spawning it, determine the effective maximum nesting depth. Use an\nexplicit positive-integer CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH value first;\nwhen it is unset, inspect claude --version (the default is 1 in 2.1.217–2.1.218\nand 3 in 2.1.219+). If the version is unavailable, conservatively use 1. At\ndepth 3+, use the deep-bug-investigator orchestrator. At depth 1 or 2, keep\norchestration in this main session: spawn the four\nfocused tracks (reproduction, root cause, impact, fix strategy) directly in\none parallel batch, wait for all four, then synthesize their evidence. Never\nspawn an orchestrator that cannot delegate.

\n

Otherwise: Run the sequential workflow below.

\n

Avoid confirmatory subagents: once Steps 3-4 identify the root cause\nwith high confidence, present it directly — four subagents (~80K tokens)\nre-verifying a finding already made in this context add cost, not evidence.

\n

Iron Laws

\n
    \n
  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. \n
  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. \n
  3. Check changeset errors before UI debugging — Silent form saves are almost always {:error, changeset} with validation failures, not viewport or JS issues
    4. \n
  4. Consult compound docs before investigating fresh — A previously solved problem saves the entire investigation cycle; always search .claude/solutions/ first
    5. \n
  5. NEVER guess at a fix before reproducing — Reproduce first, then identify root cause, then fix. Skipping steps causes wrong fixes
    6. \n
  6. DO NOT apply a fix without confirming root cause — Verify your hypothesis with evidence (logs, tests, IO.inspect) before changing code
    7. \n
\n

Investigation Workflow

\n

Step 0: Consult Compound Docs

\n

Search .claude/solutions/ for relevant keywords using Grep.

\n

If matching solution exists, present it and ask: \"Apply this\nfix, or investigate fresh?\"

\n

Step 0a: Runtime Auto-Capture (Tidewave -- PRIMARY when available)

\n

If Tidewave MCP is detected, start here instead of asking\nthe user to paste errors. Auto-capture runtime context:

\n
    \n
  1. mcp__tidewave__get_logs level: :error -- capture recent errors
    2. \n
  2. Parse stacktraces, correlate with source via\nmcp__tidewave__get_source_location
    3. \n
  3. For data bugs: mcp__tidewave__execute_sql_query to inspect state
    4. \n
  4. For logic bugs: mcp__tidewave__project_eval to test hypotheses
    5. \n
  5. For UI bugs: mcp__tidewave__get_source_location with component name
    6. \n
\n

Present pre-populated context to the user:

\n
\n

Auto-captured from runtime:

\n\n

Investigating this. Correct if wrong.

\n
\n

This eliminates copy-pasting errors between app and agent.\nIf Tidewave NOT available: Fall through to Step 1.

\n

Step 1: Sanity Checks

\n

Run mix compile --warnings-as-errors 2>&1 | head -50, then mix ecto.migrations\n(lists pending migrations without running them — ask before migrating).

\n

Step 2: Reproduce

\n

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.

\n

Step 3: Read Error LITERALLY

\n

Parse the error message — check ${CLAUDE_SKILL_DIR}/references/error-patterns.md.

\n

Step 4: Check the Obvious (Ralph Wiggum Checklist)

\n

File saved? Atom vs string? Data preloaded? Pattern match\ncorrect? Nil? Return value? Server restarted?

\n

LiveView form saves silently failing? Check changeset errors\nFIRST — not viewport, click mechanics, or JS. A missing\nhidden_input for a required embedded field causes {:error, changeset} with no visible UI feedback.

\n

Step 5: IO.inspect / Tidewave project_eval

\n

Step 6: Identify Root Cause

\n

Find what's actually happening vs what should happen.

\n

Step 7: Hand Off

\n

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

\n\n

Autonomous Iteration

\n

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

\n

References

\n\n","files":[{"path":"references/debug-commands.md","sizeBytes":1999,"isText":true},{"path":"references/error-patterns.md","sizeBytes":1237,"isText":true},{"path":"references/investigation-template.md","sizeBytes":934,"isText":true},{"path":"SKILL.md","sizeBytes":5636,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-04T15:15:01.004604Z","sha256":"81FC1586E832495CCE9A48A799E2DC3E1C1C06985FAE5F4613CA04594E106917","sizeBytes":5507},"review":null,"source":{"repositoryUrl":"https://github.com/oliver-kriska/claude-elixir-phoenix","path":"plugins/elixir-phoenix/skills/investigate","license":"MIT","commit":"9767a82d24ddddad553e85f88efc2869a7fd7d88","subtreeSha":"39B969D917252C3C627091840835571C3F932E976D0D604EBF6FFB72231A528F","lastSyncedAt":"2026-10-04T15:14:09.139242Z"},"reviewedAt":"2026-10-04T15:16:17.548162Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/investigate"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart"},{"target":"git","command":"git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git"}]}