/perf

name: perf
description: Analyze Elixir/Phoenix performance — N+1 queries, assign bloat, ecto optimization, genserver bottlenecks. Use when slowness, timeouts, or high memory reported.
effort: high
argument-hint: "[page|context|module] [--focus ecto|liveview|otp]"

Performance Analysis

Analyze code for performance issues across Ecto, LiveView, and OTP layers. Prioritize findings by impact and effort.

Usage

/phx:perf                           # Analyze full project
/phx:perf lib/my_app/accounts.ex    # Analyze specific module
/phx:perf --focus ecto              # Ecto queries only
/phx:perf --focus liveview          # LiveView memory only
/phx:perf --focus otp               # OTP bottlenecks only

Arguments

`$ARGUMENTS` = Optional module/context path and `--focus` flag.

Iron Laws

1. **MEASURE BEFORE OPTIMIZING** — Never optimize without evidence of a problem 2. **DATABASE FIRST** — 90% of Elixir performance issues are query-related 3. **ONE CHANGE AT A TIME** — Isolate optimizations to measure impact 4. **NEVER benchmark in dev mode** — Always use `MIX_ENV=prod` for performance measurements; dev mode includes code reloading, debug logging, and unoptimized compilation that invalidate results

Workflow

Step 1: Identify Scope

Check specific file if provided. Otherwise scan full project:

# Find hot paths: contexts, LiveViews, workers
find lib/ -name "*.ex" | head -50

Step 2: Run Analysis Tracks

Spawn analysis agents in parallel based on focus:

**Ecto Track** (default or `--focus ecto`):

Spawn `phx:elixir-reviewer` with prompt: "Analyze for N+1 queries, missing preloads, unindexed queries, and inefficient patterns. Check: `Repo.all` in loops, `Enum.map` with Repo calls, missing `preload`, queries without indexes on WHERE/JOIN columns."

**LiveView Track** (default or `--focus liveview`):

Spawn `phx:elixir-reviewer` with prompt: "Analyze LiveViews for memory issues: large assigns, missing streams for lists, assigns that grow unbounded, heavy `handle_info` processing, missing `assign_async` for slow ops."

**OTP Track** (only with `--focus otp`):

Spawn `phx:otp-advisor` with prompt: "Analyze for OTP bottlenecks: GenServer mailbox growth, synchronous calls in hot paths, missing Task.async for parallel work, ETS opportunities for read-heavy state."

Step 3: Prioritize Findings

Score each finding on a 2x2 matrix:

| | Low Effort | High Effort | |---|---|---| | **High Impact** | DO FIRST | PLAN | | **Low Impact** | QUICK WIN | SKIP |

High impact = affects response time, memory per user, or query count. Low effort = single file change, no migration needed.

Step 4: Present Top 5

Present findings sorted by priority:

## Performance Analysis: {scope}

### 1. {Finding} — DO FIRST
**Impact**: {what improves}
**Location**: {file}:{line}
**Current**: {problematic pattern}
**Fix**: {optimized pattern}
**Estimated gain**: {e.g., "eliminates N+1, reduces queries from O(n) to O(1)"}

### 2. {Finding} — PLAN
...

Step 5: Offer Next Steps

Always end with actionable next steps — findings without follow-up get lost. Present options based on severity:

How would you like to proceed?

- `/phx:plan` — Create a plan from these findings (recommended for 3+ fixes)
- `/phx:quick` — Apply top priority fix directly (1-2 simple fixes)
- `/phx:investigate` — Deep-dive into a specific finding

Tidewave Integration

If Tidewave MCP is available:

• Use `mcp__tidewave__project_eval` to run `Repo.query!("EXPLAIN ANALYZE ...")` on suspicious queries
• Use `mcp__tidewave__project_eval` to check `Process.info(pid, :message_queue_len)` for GenServer bottlenecks
• Use `mcp__tidewave__execute_sql_query` to check missing indexes

References

• `${CLAUDE_SKILL_DIR}/references/benchmarking.md` — Benchee patterns, profiling, flame graphs