phx-trace

Name: phx-trace
Author: oliver-kriska/claude-elixir-phoenix

$npx mdskill add oliver-kriska/claude-elixir-phoenix/phx-trace

Trace Elixir call trees from entry points via mix xref for debugging

Identify all callers of a function to understand its data flow.
Depends on `mix xref callers` command and manual inspection of results.
Decides by analyzing the provided function calls and argument patterns.
Delivers insights into how the function is called and where it originates.

SKILL.md

.github/skills/phx-traceView on GitHub ↗

---
name: phx-trace
description: Trace Elixir call trees from entry points via mix xref. Use when debugging
  data flow, planning signature changes, or understanding how a bug reaches code.
---

# Call Tracing

Build call trees showing how functions are reached from entry points.

## Iron Laws - Never Violate These

1. **Always use `mix xref callers` first** - It's authoritative; grep is fallback only
2. **Stop at entry points** - Controllers, LiveView callbacks, Oban workers, GenServer callbacks
3. **Track visited MFAs** - Prevent infinite loops from circular calls
4. **Extract argument patterns** - Just knowing "who calls" isn't enough; HOW they call matters
5. **Max depth 10** - Deeper trees indicate architectural issues, not useful traces

## When to Build Call Tree (Use Proactively)

| Condition | Why Call Tree Helps |
|-----------|---------------------|
| Unexpected nil/value at runtime | Trace where the value originates |
| Bug can't reproduce locally | See all entry points that reach the code |
| Changing function signature | Find all callers and their argument patterns |
| Incomplete stack trace | Get full path context |
| "Where does X come from?" | Visual answer to data flow question |

## Quick Trace

Run `mix xref callers MyApp.Accounts.update_user/2` to find all callers. Then read the reported locations to see argument patterns.

## Entry Points (Stop Here)

| Pattern | Type |
|---------|------|
| `def mount/3`, `def handle_event/3` | LiveView |
| `def index/2`, `def show/2`, `def create/2` | Controller |
| `def perform(%Oban.Job{})` | Oban Worker |
| `def handle_call/3`, `def handle_cast/2` | GenServer |

## Delegate to call-tracer Agent

For full recursive tree with argument extraction and **parallel category tracing**:

```
Agent(subagent_type: "call-tracer", prompt: "Build call tree for MyApp.Accounts.update_user/2")
```

The call-tracer agent uses **parallel subagents** for each entry point category:

- Controllers subagent (HTTP paths)
- LiveView subagent (WebSocket paths)
- Workers subagent (Background jobs)
- Internal subagent (Cross-context calls)

Each gets fresh 200k context for deep exploration.

## Output Location

`.claude/plans/{slug}/research/call-tree-{function}.md`

## References

For detailed patterns:

- `references/mix-xref-usage.md` - Full mix xref commands and options
- `references/entry-points.md` - All Phoenix/OTP entry point patterns
- `references/argument-extraction.md` - AST parsing for argument patterns

More from oliver-kriska/claude-elixir-phoenix

Skill	Description
ash-framework	Ash Framework — resources, actions, policies, aggregates, calculations, AshPhoenix.Form, LiveView, migrations. Use when generating resources via mix ash.codegen, editing changes, checks, types, validations, or domain code interfaces.
catchup	Summarize and review what changed while you were away. Use after a weekend, vacation, or flight to check missed PRs, git commits, Linear tickets, and meetings — one prioritized brief, not a firehose.
cc-changelog	\|
codex-ab	Run an A/B codex review experiment — holistic codex review vs 3 focused dimension passes (security, ecto, liveview) on the branch diff, classify findings, report a panel-value verdict. Use when the branch is fresh, before any codex review runs.
compound-docs	Searchable Elixir/Phoenix/Ecto solution documentation system with YAML frontmatter. Builds institutional knowledge from solved problems. Use when consulting past solutions before investigating new issues.
docs-check	\|
ecto-n1-check	Detect N+1 query anti-patterns specifically — Repo calls inside Enum/for
ecto-patterns	Ecto patterns — schemas, changesets, queries, migrations, Multi, associations, preloads, upserts. Use when editing Repo calls, Ecto.Query, or schema fields. Skip for Ash.
ecto:constraint-debug	Debug Ecto constraint violations - trace triggers, check migrations, find duplicate data. Use when seeing unique_constraint, foreign_key_constraint, or check_constraint errors.
ecto:n1-check	Detect N+1 query anti-patterns specifically — Repo calls inside Enum/for loops, missing preloads on associations. Use when N+1 is explicitly suspected, NOT for unrelated Ecto questions or wider database performance.