code-trace

Codex Compatibility

When running this skill in Codex, translate Claude Code-only primitives before acting: AskUserQuestion -> chat/request_user_input, TodoWrite -> update_plan, Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent when available and allowed, and EnterPlanMode/ExitPlanMode -> a concise chat plan plus explicit approval. Resolve Read/Write/Edit/Bash/WebSearch/WebFetch to Codex file/shell/web tools, and map ~/.claude/... paths to ~/.agents/... or ~/.codex/... unless the task explicitly targets Claude Code.

Cursor Compatibility

When running this skill in Cursor Agent, translate Claude Code-only primitives before acting: AskUserQuestion -> AskQuestion; TodoWrite -> Cursor TodoWrite or an equivalent checklist; Task/TaskCreate/TeamCreate/SendMessage/multi-agent flows -> Cursor Task (subagents), parallel Tasks, or run_in_background when allowed (TeamCreate/SendMessage may have no exact match); EnterPlanMode/ExitPlanMode -> Plan mode (SwitchMode / CreatePlan) plus explicit user approval. Resolve Read/Write/Edit/StrReplace/Bash/web/search/MCP via Cursor Composer or Agent equivalents. MCP names written as mcp__server__tool typically map to call_mcp_tool with configured server identifiers. Map ~/.claude/... to ~/.cursor/skills/, .cursor/skills/, and .cursor/rules/ unless the task explicitly targets Claude Code.

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

1. Location: File + line range + function name
2. Code: Full source (no abbreviation)
3. What: Brief summary of what the code does
4. Why: Why this step exists in the flow
5. 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>

## What would you like to trace?

1. Trace a request flow - Follow HTTP request from receipt to response
2. Trace a function call - Follow a specific function through the codebase
3. 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.

| Response | Workflow | |----------|----------| | 1, "request", "HTTP", "route", "API", "endpoint", "POST", "GET" | `workflows/trace-request.md` | | 2, "function", "call", specific function name | `workflows/trace-function.md` | | 3, "resume", "continue", "previous" | Read Serena memory for `trace_session_*` |

Before Starting Any Workflow

1. Detect Framework: Run scripts/detect-framework.sh to identify:

   • Express, Next.js (App/Pages), Fastify, Hono, NestJS, Koa, or generic

2. Load Framework Patterns: Read references/framework-patterns.md section for detected framework

3. 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>

## Boundaries

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)