<essential_principles>
How Code Tracing Works
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 </essential_principles>
- 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 framework - Prepare Serena: Ensure Serena MCP is available for:
- find_symbol() - Locate functions/handlers - find_referencing_symbols() - Find callers - get_symbols_overview() - Map module structure - write_memory() / read_memory() - State persistence
After determining intent and framework, read the appropriate workflow and follow it.
<reference_index>
References
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 |
| </reference_index> |
<workflows_index>
Workflows
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 |
| </workflows_index> |
<scripts_index>
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</scripts_index>
<success_criteria> A successful code trace:
- Entry point correctly identified and explained
- Framework detected and appropriate patterns applied
- At least one branch point presented as interactive choice
- External dependencies summarized (not deep-traced)
- User navigated to terminal point OR chose to stop
- Path history shown in ASCII flowchart format
- Mermaid flowchart offered as output option (if trace completed)
- Key insights collected and displayed
- Trace state available for resume (if user chose to save) </success_criteria>
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)