cofin/tracer

Tracer

Systematic code exploration that builds understanding incrementally by tracing execution paths and mapping dependencies, rather than randomly reading files. Start at a known entry point and follow connections outward, building a map as you go.

<workflow>

Workflow

1. Identify the Entry Point

What's the starting location? An API endpoint, a function call, a config file, a user action. Be specific — "the auth system" is too vague; POST /api/auth/login is an entry point.

2. Read the Entry Point

Understand what it does. Note every outgoing call or dependency.

3. Choose a Branch

Pick the most relevant outgoing connection to follow. Don't try to trace everything at once — choose the branch most likely to answer the question.

4. Follow the Chain

Read the next file/function. Note what it calls. Add to the map. Repeat.

5. Record the Path

Maintain a running trace: A → B → C → D. Include file paths and line numbers.

What to record at each node:

• File path and function/class name
• What it does (one sentence)
• What it calls (outgoing edges)
• Data transformations (what goes in, what comes out)

6. Decide: Deeper vs Wider

• Branch understood → backtrack and follow a different branch from an earlier node
• Branch is critical → keep going deeper
• Question answered → stop and synthesize

7. Synthesize the Map

When enough of the system is traced, describe the overall flow. Connect the nodes into a coherent narrative that answers the original question.

When to stop:

• Leaf reached (DB query, external API call, stdlib function)
• Boundary crossed (third-party library internals)
• Question answered
• Critical path covered

</workflow>

Trace Mode Selection

Pick the mode based on the question being asked:

| Mode | Question | Best for | |------|----------|----------| | Execution | "What happens when X is called?" | Request flows, feature behavior | | Dependency | "What depends on X?" | Impact analysis, refactoring | | Data | "How does data get from A to B?" | Data pipeline debugging |

For complex investigations, start with execution trace for the happy path, then dependency trace on key components, then data trace on critical structures. See references/trace-modes.md for detailed mode descriptions.

<guardrails>

Guardrails

• Never read a file without knowing WHY. Every file must be because the previous file pointed you there. If you can't say "I'm reading this because X imports/calls it," you're guessing.
• Don't trace everything at once. Choose branches deliberately. Breadth-first exploration builds no understanding.
• Don't skip recording. If you read a file and don't add it to the map, the trace is incomplete.
• Don't cross boundaries unnecessarily. Third-party library internals are rarely worth tracing unless the bug is there.

</guardrails> <validation>

Validation Checkpoint

Before presenting the trace, verify:

• [ ] Every file read was because a previous file pointed to it
• [ ] Path recorded with file paths and line numbers
• [ ] Map answers the original question
• [ ] Stop conditions were respected (didn't over-trace or under-trace)

</validation> <example>

Example

Trace: "What happens when POST /api/users is called?"

| Node | File | Function | Calls | Data | |------|------|----------|-------|------| | 1 | src/routes/users.ts:14 | createUser | UserService.create() | req.body → {name, email} | | 2 | src/services/user.ts:42 | create() | validate(), UserRepo.insert() | {name, email} → UserDTO | | 3 | src/repos/user.ts:28 | insert() | db.query() | UserDTO → SQL INSERT | | 4 | (leaf) | PostgreSQL | — | INSERT INTO users... |

Path: POST /api/users → createUser → UserService.create → UserRepo.insert → SQL INSERT.

</example>

Complements

• systematic-debugging — provides the "understand the system" phase before hypothesis formation
• brainstorming — understanding existing code before designing changes
• flow-research — structured codebase investigation

References

• Tracing Strategy — Core principle, seven-step workflow, what to record at each node, when to stop
• Trace Modes — Execution trace, dependency trace, data trace, and combining modes