tomevault-io This skill traces code execution paths interactively, letting you navigate through the codebase like a debugger stepping through code - but with rich explanations at each step.
Principle 1: Application Boundary
Trace ONLY application code. External dependencies (node_modules, vendor/) receive:
- A summary of what they do
- Link to official documentation
- NOT deep-traced into their internals
Why: External libraries can be 100K+ lines. Tracing into them wastes context and obscures the actual application logic. The goal is understanding YOUR code, not library internals.
Principle 2: Interactive Navigation
Every conditional branch becomes a user choice:
| Code Pattern | Presentation |
|---|---|
if/else |
"Path A: condition true" vs "Path B: condition false" |
switch |
One choice per case |
try/catch |
"Success path" vs "Error path" |
async/await |
Option to trace into called functions |
Why: Linear traces miss important paths. Interactive navigation lets users explore exactly what they're interested in.
Principle 3: Progressive Explanation
Each step includes:
- Location: File + line range + function name
- Code: Full source (no abbreviation)
- What: Brief summary of what the code does
- Why: Why this step exists in the flow
- Next: What happens next (or choices if branching)
Use thinking markers (🤔🎯⚡📊💡🔐) for clarity.
Principle 4: State Persistence
Trace state is stored in Serena Memory to enable:
- Resuming interrupted traces
- Backtracking to previous decision points
- Saving completed traces for future reference
- Trace a request flow - Follow HTTP request from receipt to response
- Trace a function call - Follow a specific function through the codebase
- Resume previous trace - Continue from where you left off
Please provide additional context:
- For request tracing: Which endpoint? (e.g., "POST /api/users")
- For function tracing: Which function? (e.g., "validateUser" or "src/utils/auth.ts:checkToken")
Wait for response before proceeding.
Before Starting Any Workflow
Detect Framework: Run
scripts/detect-framework.shto identify:- Express, Next.js (App/Pages), Fastify, Hono, NestJS, Koa, or generic
Load Framework Patterns: Read
references/framework-patterns.mdsection for detected frameworkPrepare Serena: Ensure Serena MCP is available for:
find_symbol()- Locate functions/handlersfind_referencing_symbols()- Find callersget_symbols_overview()- Map module structurewrite_memory()/read_memory()- State persistence
After determining intent and framework, read the appropriate workflow and follow it.
All in references/:
| File | Content |
|---|---|
| framework-patterns.md | Entry point detection and request flow for Express, Next.js, Fastify, etc. |
| control-flow-types.md | How to present if/switch/try/loops as interactive choices |
| explanation-style.md | Thinking markers, step format, summary format |
| mermaid-templates.md | Mermaid.js flowchart generation from trace path_history |
All in workflows/:
| Workflow | Purpose |
|---|---|
| trace-request.md | Trace HTTP request from entry to response |
| trace-function.md | Trace a specific function's call chain |
Scripts
| Script | Purpose |
|---|---|
| detect-framework.sh | Auto-detect project framework from package.json |
Usage:
./scripts/detect-framework.sh /path/to/project
# Output: express | nextjs-app | nextjs-pages | fastify | hono | nestjs | koa | generic
Will:
- Trace application code with full source display
- Explain each step with thinking markers
- Present conditional branches as interactive choices
- Summarize external dependencies at the boundary
- Persist trace state for resume capability
Will Not:
- Deep-trace into node_modules or external libraries
- Execute or run the code (read-only analysis)
- Modify any source files
- Make assumptions about runtime values (present all branches)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.