Skip to content

Unique-AG/ai / .claude/skills/trace

Navigate execution flow from an entry point, mapping call chains, external dependencies, and side effects.

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:

ClassificationLabelCriteria
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:

FileRole
src/payments/checkout.pyEntry point — orchestrates the order flow
src/validators.pyValidates cart contents before payment
src/payment.pyHandles 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.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall