---

name: trace description: "Use when debugging how a value or request reaches Elixir code, finding who calls a function, or planning a signature change. Builds the call tree with mix xref callers instead of reading files one by one." effort: medium

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 the caller query first, then inspect another function in the chain as needed:

mix xref callers MyApp.Accounts.update_user/2
mix xref callers MyApp.Accounts.get_user/1

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:

Determine the effective maximum nesting depth. Use an explicit positive-integer CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH value first; when it is unset, inspect claude --version (the default is 1 in 2.1.217–2.1.218 and 3 in 2.1.219+). If the version is unavailable, conservatively use 1. At depth 2+, delegate to the orchestrator below. At depth 1, keep orchestration in this main session: spawn the applicable controller, LiveView, worker, and internal tracing prompts directly, then merge their results. Never spawn an orchestrator that cannot delegate.

Agent(subagent_type: "phx: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 a fresh context for deep exploration.

Output Location

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

References

For detailed patterns:

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