---
name: to-callgraph
description: Trace a code path end-to-end and render it as an annotated ASCII callgraph with a concurrency/serialization analysis.
disable-model-invocation: true
---

# To-Callgraph

Trace a flow through the codebase end-to-end and hand back a callgraph: an ASCII diagram of every hop, annotated with where work runs concurrently and where it waits. When the user asks about a path — a feature, a flow, a worry like "can we parallelize this?" — the answer starts with the trace.

## 1. Scope the trace

Pin the **entry** (the event/message/command that starts the flow) and the **exit** (what completes it — a rendered frame, a blob URL, a persisted row). Find every path that carries the feature's name: a feature often has two (a CPU preview path and a GPU path, a fast path and a full path), and each gets traced.

Completion criterion: you can state, in one sentence, what enters and what exits each path.

## 2. Walk the hops

Each hop is one box of the callgraph: `event → message → update → command → service → worker/GPU → message → update → model → view`. Read the file that handles each hop before drawing the edge — a hop you haven't read is an edge you can't draw.

- Recon the area first: `fffind`/`grep` for the feature's names, read what surfaces, then read the project's ADRs/docs for the decisions that shaped the path.
- Before trusting an edge, `grep` for every caller of the exported symbols it crosses — missed callers are bugs.
- Note the runtime's execution model: are commands forked (concurrent) or queued? That determines which hops are already parallel.

Completion criterion: every edge names a file you actually read; every exported symbol you cite has had its callers grepped.

## 3. Render the callgraph

ASCII, top-down, one line per hop, file path on the edge, in the house style:

```
<entry>
  └─ <dispatch> → <message>
       └─ <command.execute>        (forked — concurrent)
            ├─ <service>           ✓ memoized / parallel
            └─ <worker>            ⚠ serializes here — one thread, N requests
```

Mark every async boundary (`postMessage`/Deferred, `Effect.runFork`, GPU submission). Mark every hop that already runs concurrently (✓) and every hop where work queues up (⚠). If a hop spans multiple files, say so.

Completion criterion: a reader can point at any box, ask "where's the code?", and get a file:line.

## 4. Read the seams

For every ⚠, name the concrete cost and the fix shape: a **pool** (N workers/threads instead of 1), a **cache** (memoize a value recomputed per iteration), a **move** (off the main thread), a **coalesce** (dedupe identical requests). Also hunt **wasted work**: the same op repeated per item that could run once (a downscale per LUT instead of per photo). Every bottleneck gets a named fix direction — a complaint without a fix shape is an unfinished seam.

Completion criterion: every ⚠ and every repeated-op finding carries a named fix shape.

## 5. Deliver

Callgraph first, then: what's already parallel, where it serializes, options ranked by cost/benefit, and the recommended cut. When the user asks for a plan, add before/after callgraphs plus a file-by-file change list and how to verify (tests, typecheck, lint, manual smoke).

Completion criterion: the user can approve or reject the recommendation from your writeup alone.