Trace

Code Tracer

Given a piece of code, a symbol, or a file reference, trace it through the stack and produce a diagram showing where it sits, what calls it, and what it depends on.

Step 1: Identify the Input

The input is one of:

• Selected code — a method, class, block, or snippet pasted directly
• Symbol name — a method name, class name, or route (e.g. InvoiceService#create, POST /invoices)
• File reference — a path with optional line number (e.g. app/services/invoice_service.rb:42)

If no input is provided, ask: "What code do you want to trace? Paste a snippet, name a method or class, or give a file path."

Step 2: Detect the Stack

Identify the framework before tracing — conventions differ significantly:

Step 3: Locate the Code

Find the actual source before tracing:

• If given a symbol name, use grep/find to locate the definition
• If given a file reference, read the file at that line
• If given a snippet, grep for a distinctive identifier to find where it lives

Read the located code closely before tracing.

Step 4: Classify the Code

Determine what layer the code belongs to. Use the detected stack's conventions:

Step 5: Trace

Follow references/playbook.md for the full trace procedures, including detailed steps for each direction, handling of inheritance/polymorphism/god objects, and how to handle ambiguous traces with multiple entry points.

Summary:

Trace upward (toward the entry point / caller):

• Find what calls this code — grep for the method name, class instantiation, or route
• Follow the chain: caller → caller's caller → entry point
• Stop when you reach a route definition, job enqueue, webhook receiver, or console/CLI call

Trace downward (toward data and dependencies):

• Find what this code calls — read the method body and identify all outbound calls
• Follow into service objects, models, external clients, and jobs
• Stop at the data layer (database query, cache read, external API call, file I/O)

Trace laterally (cross-cutting concerns):

• Identify callbacks, hooks, observers, or event publishers triggered along the path
• Note authorization checks (policy, middleware, before_action) and what happens on failure
• Note audit logging, analytics events, and instrumentation (ActiveSupport::Notifications, StatsD, Sentry breadcrumbs)
• Flag any async handoffs (background jobs, ActionCable broadcasts, webhooks out)

If the trace gets complex — deep inheritance, polymorphic dispatch, god objects, or dynamically-generated methods — read the "Handling Common Complexity" section in playbook.md before continuing.

If the input could belong to multiple flows — read "When the Trace Is Ambiguous" in playbook.md and ask the user to clarify before tracing.

Step 6: Output

Present a vertical stack diagram, then a prose walkthrough.

Stack diagram format

[Entry point]         e.g. POST /invoices → InvoicesController#create
  ↓
[Controller/Handler]  e.g. InvoicesController#create
  ↓
[Service/Logic]       e.g. InvoiceService#create
  ↓ (async)
[Background Job]      e.g. SendInvoiceEmailJob
  ↓
[Model/Data]          e.g. Invoice.create!, LineItem.insert_all
  ↓
[External/Storage]    e.g. Stripe API, PostgreSQL

Use ↓ for synchronous calls, ↓ (async) for background/async handoffs, → for lateral triggers (callbacks, events). Use actual names from the codebase — not generic placeholders.

After the diagram, write 3–5 sentences explaining how data flows through these layers for this specific code path. Note any non-obvious hops, authorization points, or side effects.

File references

Use clickable [file:line](path/to/file#Lline) links for every layer cited.

Want to go deeper?

End with 2–3 specific follow-up suggestions based on the trace — e.g.:

• Dig into one layer of the trace that has complex logic
• Find the tests that cover this code path
• Trace a related flow that shares some of these layers
• See what happens when this flow fails (error handling path)