/trace

Trace the execution path of a request or operation through the codebase.

Steps

1. Identify the starting point: HTTP request handler, event listener, CLI command, or function call. 2. Follow the execution path step by step:

• Map each function call from entry to exit.
• Note middleware, interceptors, or decorators in the chain.
• Track data transformations at each step.
• Identify async boundaries (awaits, callbacks, event emissions).

3. For each step in the trace, document:

• File and function name.
• Input parameters and their values/types.
• Side effects (database queries, API calls, file writes).
• Return value or thrown error.

4. Identify potential failure points:

• Unhandled errors or missing try/catch blocks.
• Implicit type conversions or coercions.
• Missing validation at boundaries.

5. Generate a sequence diagram of the execution flow. 6. Highlight any performance bottlenecks (blocking I/O, N+1 queries).

Format

Trace: <operation name>

1. [entry.ts:handleRequest] <- HTTP POST /api/users
2. [middleware/auth.ts:verify] <- checks JWT token
3. [services/user.ts:create] <- validates input, calls DB
4. [db/queries.ts:insert] <- INSERT INTO users ...
5. [services/user.ts:create] -> returns { id, email }
6. [entry.ts:handleRequest] -> 201 Created

Side effects: 1 DB write, 1 email sent
Potential issues: No transaction wrapping steps 4-5

Rules

• Follow the actual code path, not assumptions about what it should do.
• Include error handling paths, not just the happy path.
• Note where logging exists and where it is missing.
• Flag any implicit dependencies or global state access.