trace

What I do

I map execution flow from a given entry point — a file path, function name, or class name — and produce two things:

1. Mermaid flow diagram — a graph TD call graph showing which functions call which, with external dependencies (APIs, databases, queues, file I/O) styled distinctly. Ambiguous callees, truncation points, and cycles are marked explicitly in the diagram.
2. Structured markdown summary — a full breakdown covering: call chain narrative, key files and their roles, external dependencies (name, protocol, call site), side effects (file writes, network calls, state mutations), ambiguities and truncations, and a one-paragraph entry-to-exit narrative.

I trace the call graph depth-first up to 3 levels by default. I work with any programming language — I read the code semantically, so no static analysis tools are required.

When to use me

Use me when you:

• Pick up an unfamiliar module or function and need to understand what it does and what it touches before making changes
• Are about to refactor a function or class and need to know the blast radius — what calls into it, what it calls out to, and what side effects are involved
• Want a specific question answered about a piece of code (e.g., "what external services does this touch?") without reading every file manually
• Need to orient a new team member in a complex flow
• Are debugging an unexpected side effect and need to map where state mutations happen

Example usage

/trace src/payments/checkout.py

→ Full trace from the checkout.py entry point: call chain, all files involved, external dependencies highlighted

/trace AuthService.authenticate

→ Blast-radius map: everything that calls authenticate (callers) and everything it delegates to (callees + side effects)

/trace payments/checkout.py "what external services does this touch?"

→ Focused trace: leads with a direct answer listing all external services, then provides the full trace for context

How to respond

Step 1 — Parse input

Extract the entry point from the invocation:

• Accept a file path (e.g., src/payments/checkout.py), a function name (e.g., process_order), or a class name (e.g., AuthService)
• Accept an optional focus question as a second argument — plain text after the entry point
• If the entry point is ambiguous (name matches multiple functions/files), ask the user to clarify before proceeding

Step 2 — Locate the entry point

Search the codebase for the entry point:

• For file paths: confirm the file exists; identify the top-level functions/classes as the trace root
• For function/class names: search across all files; if multiple matches exist, list them and ask which to trace
• If the entry point is not found: stop immediately and report: "Entry point <name> not found in the codebase. Check the spelling or provide the file path directly."

Step 3 — Trace the call graph (depth-first, 3 levels)

Starting from the entry point, traverse outbound calls:

• For each function/method: record its name, file path, and all outbound calls it makes
• Recurse into each callee, up to 3 levels deep (configurable — user can request deeper: "trace up to 5 levels")
• When the depth limit is reached: mark the node as [TRUNCATED at depth N] and stop recursing that branch
• Do not re-read files you have already traced — if a node appears again, mark it as [CYCLE] and stop

Step 4 — Classify each node

For every node in the call graph, classify it as one of:

Classification	Label	Criteria
Internal	(no label)	Function/method owned by the project
External	[EXTERNAL]	Crosses the codebase boundary: HTTP calls, DB queries, file I/O, message queue publish/consume, event emissions
Ambiguous	[AMBIGUOUS]	Callee cannot be statically determined: dynamic dispatch, dependency injection, reflection, eval()

For External nodes, record: what system it connects to (e.g., "Stripe API", "PostgreSQL", "S3"), the call site (file + line or function), and the protocol/method (HTTP POST, SQL SELECT, etc.).

Step 5 — Detect side effects

Identify and list all side effects encountered during the trace:

• File writes (creating, updating, or deleting files)
• Network calls (HTTP requests, socket connections)
• State mutations (writes to shared state, cache updates, session changes)
• External integrations (database writes, queue publishes, event emissions)

Step 6 — Handle cycles and truncations

• Cycles: When a node would be visited a second time, insert a [CYCLE → <original-node>] marker in the diagram and note it in the Ambiguities section
• Truncations: When the depth limit stops recursion, insert a [TRUNCATED] node in the diagram and note it in the Ambiguities section with the path that was cut off

Step 7 — Apply focus question (if provided)

If a focus question was given:

• Identify which nodes and edges in the call graph are most relevant to answering it
• Prepare a direct answer (1–3 sentences) to lead the output — answer the question first, before the diagram
• Emphasise relevant nodes in the summary (list them first in their respective sections)
• The full trace is still produced — the focus question changes prioritisation, not scope

Step 8 — Produce output

Always produce two parts in this order:

---

Part 1: Mermaid diagram

graph TD
    entryNode["file.py\nfunction_name()"]
    internalNode["other_file.py\ncalled_function()"]
    extNode["[EXTERNAL]\nStripe API (HTTP POST)"]:::external
    ambigNode["[AMBIGUOUS]\ndynamic_handler()"]:::ambiguous
    truncNode["[TRUNCATED at depth 3]"]:::truncated
    cycleNode["[CYCLE → entryNode]"]:::cycle

    entryNode --> internalNode
    entryNode --> extNode
    internalNode --> ambigNode
    internalNode --> truncNode
    entryNode -.-> cycleNode

    classDef external fill:#fef3c7,stroke:#d97706,stroke-dasharray: 5 5
    classDef ambiguous fill:#fee2e2,stroke:#dc2626,stroke-dasharray: 3 3
    classDef truncated fill:#f3f4f6,stroke:#9ca3af
    classDef cycle fill:#ede9fe,stroke:#7c3aed

Node label format: "filename.ext\nfunction_name()" — file on the first line, function on the second.

---

Part 2: Structured summary

Always include all eight sections. Use "None" for empty sections — never omit a section.

Entry point: function_name() in path/to/file.ext

Call chain: [Prose narrative — describe the flow in plain English. E.g.: "process_order validates the cart via validate_cart, then delegates payment to charge(), which calls the Stripe API synchronously. On success, the order record is persisted to PostgreSQL via the ORM."]

Key files & their roles:

File	Role
src/payments/checkout.py	Entry point — orchestrates the order flow
src/validators.py	Validates cart contents before payment
src/payment.py	Handles Stripe integration

External dependencies:

• Stripe API — HTTP POST — called from payment.py::charge()
• PostgreSQL — SQL INSERT — called from checkout.py::process_order() via ORM

Side effects:

• Database write: order record created in orders table
• Network call: Stripe charge initiated (synchronous)

Ambiguities & truncations:

• [AMBIGUOUS] dynamic_handler() in checkout.py — callee determined at runtime via DI container; cannot be statically resolved
• [TRUNCATED] notification_service.send() branch cut at depth 3 — may contain additional side effects

Narrative: [One paragraph summarising the full entry-to-exit flow, written for a developer who has never seen this code. Cover: what the function does, the key path through the call graph, what external systems are touched, and any important ambiguities or side effects to be aware of.]

---

Blast radius section (when entry point is a function or class)

When the entry point is a function or class (not a file), add this additional section to the summary:

Blast radius:

• Callers (code that calls <entry>): [list each caller with file path]
• Callees (code <entry> delegates to): [list each callee with file path]
• Impact statement: Modifying <entry> is likely to affect: [caller list]

Search the codebase for direct callers of the entry point and include them. This is the pre-refactor scoping view.

Focus question mode (when a second argument is provided)

When a focus question is provided (e.g., /trace checkout.py "what external services does this touch?"):

1. Run the full trace as normal — do not skip any step

2. Before producing output, identify which nodes and edges most directly answer the question:

   • "what external services does this touch?" → prioritise all [EXTERNAL] nodes
   • "what writes to the database?" → prioritise nodes with SQL/ORM side effects
   • "what could fail due to a network error?" → prioritise external HTTP calls
   • "what does this mutate?" → prioritise state mutation side effects

3. Lead the output with a Focus Answer section:

   Focus Answer: [1–3 sentences directly answering the question. E.g.: "This flow touches two external services: the Stripe API (HTTP POST from payment.py::charge()) and PostgreSQL (SQL INSERT from checkout.py::process_order())."]

4. In the structured summary, list the most relevant items first in their sections (external deps, side effects, etc.) — do not remove other items, just reorder to foreground what the question asks about

5. In the Mermaid diagram, add a comment above relevant nodes (e.g., %% answers focus question) — the visual structure is not changed, but the comment aids orientation

The focus question narrows attention, not scope. The complete trace is always produced.