| name | walkthrough |
| description | Explain how a feature/flow works in this codebase as a code-flow DIAGRAM plus a high-level guided walkthrough — from the entry point down through the layers, with clickable file:line references and architecture-boundary annotations. Read-only (never edits code). Invoke /walkthrough <feature, flow, or entry point>, e.g. /walkthrough the acquire process or /walkthrough scripts/acquire.ts. |
| allowed-tools | Bash(grep *) Bash(git grep *) Bash(rg *) Bash(ls *) Bash(find *) Read(*) Grep(*) Glob(*) |
| disable-model-invocation | true |
walkthrough — explain a flow, with a diagram
Produce the kind of explanation that orients someone fast: a small ASCII
call-flow diagram at the top, then a numbered narrative that walks the
chain hop by hop. Read-only — this skill explains code, it never changes it.
When to use
/walkthrough <target> where target is a feature, a flow, or an entry point
("the acquire process", "scripts/acquire.ts", "how retrieval ranks results").
If no target is given, ask for one (or offer the obvious entry points you find).
The output shape (always both)
- A diagram — top is the entry point; arrows flow downward through each
hop/layer. Annotate architectural seams inline (which box is a context vs. an
adapter vs. pure data vs. the composition root). Keep it to ~one screen.
- A numbered narrative — one step per hop. Each step leads with what it
does and why (architecture altitude), names the module/boundary it lives in,
and cites the exact code as a clickable
path:line reference.
End by offering to zoom into any single step.
Procedure
- Find the entry point. Locate where the flow starts (a
scripts/* runner,
an exported function, an HTTP/MCP handler, a CLI command in package.json).
- Trace the chain. Follow calls/imports outward, hop by hop, reading just
enough of each file to know what it does and what it calls next. Note where a
call crosses an architecture boundary (context → port, composition root →
adapter, etc.).
- Pin accurate anchors. Before citing line numbers,
grep -n / git grep -n
for the function/symbol so every path:line reference is correct and
clickable. Wrong line numbers are worse than none.
- Render the diagram, then the narrative. Lead each step with the what/why;
keep file-level mechanics inside the step, not in the summary.
Style
- Plain language first; the reader holds the architecture, you supply the map.
- Don't paste big code blocks — explain them and point to
path:line.
- Use this repo's vocabulary when relevant (contexts, ports, adapters,
composition root, the import law) — see
docs/architecture.md §5.
- Be honest about gaps: if a hop is stubbed, deferred, or unverified, say so.
