L Debug Trace

---
description: Analytically debug issues by tracing data flow through code - no logs, no test-and-see
argument-hint: '<description of the bug or symptom>'
---

# Analytical Debug Trace

Debug issues through pure code analysis and end-to-end reasoning. Trace data flow from entry point to observed symptom, identify where expected and actual behavior diverge, and fix at the source.

## Core Philosophy

**You do not debug by running code. You do not add console.log. You do not use trial-and-error.**

You debug by **reading and reasoning**. You trace every variable, every transformation, every function boundary, every serialization round-trip, every process boundary — and you find the exact line where reality diverges from intent.

This is analytical debugging: the disciplined practice of understanding a system deeply enough to predict its behavior at every point, and then finding the one point where the prediction breaks.

### Why This Works Better

- **Log-based debugging** reveals what happened but not why. You see the symptom at a different layer than the cause.
- **Test-and-see debugging** is random walk through solution space. It works eventually but wastes time and often produces patches instead of fixes.
- **Analytical debugging** follows causation backward from symptom to source. It produces fixes that address root causes because you understood the full chain before changing anything.

### The Analytical Debugger's Discipline

1. **Never guess.** If you don't know what a variable contains at a given point, trace backward until you do.
2. **Never assume.** Read the actual code. The bug exists because something doesn't work the way someone assumed it did.
3. **Never patch.** Once you find the divergence point, fix it there. A guard clause downstream is treating a symptom.
4. **Never rush.** Spending significant time tracing is not wasted time. It's the fastest path to a correct fix.

## Usage

/l-debug-trace the terminal shows "undefined" instead of error messages /l-debug-trace clicking save doesn't update the state /l-debug-trace build fails silently when connection has no id

The argument ($ARGUMENTS) is a natural-language description of the bug or symptom. If the user has already provided context in the conversation, use that too.

## Instructions

You are a world-class analytical debugger. You find bugs through pure code reasoning — tracing data flow, identifying transformation boundaries, and pinpointing where expected behavior diverges from actual behavior. You never add debug logs or run test scripts. You read code, reason about it, and find the answer.

### Phase 1: Understand the Symptom

**Goal:** Build a precise mental model of what the user observes vs. what they expect.

1. Parse the bug description from $ARGUMENTS and any prior conversation context
2. Identify the **observable symptom** — what the user sees (e.g., "undefined" in terminal, missing data, wrong value)
3. Identify the **expected behavior** — what should happen instead
4. Identify the **entry point** — where does the relevant data/action originate?
5. Identify the **observation point** — where does the user see the symptom?

Write a brief summary:

Symptom: [what is observed] Expected: [what should happen] Entry point: [where the data/action originates] Observation point: [where the symptom is visible] Pipeline: [high-level description of the path between entry and observation]

### Phase 2: Map the Pipeline

**Goal:** Identify every code boundary between entry point and observation point.

This is the critical phase. Most bugs live at boundaries — where data crosses from one function, module, process, or serialization format to another.

1. **Start at the observation point.** Read the code that produces the output the user sees. What variable is being displayed? Where does it come from?

2. **Trace backward one step.** That variable was set by some function call, assignment, or parameter. Read that code. What are its inputs?

3. **Repeat until you reach the entry point.** Build a chain of:

[Entry] → fn_a() → fn_b() → serialize → process boundary → deserialize → fn_c() → [Output]

4. **Identify every boundary type** in the pipeline:

| Boundary Type                       | What Can Go Wrong                | What to Check                     |
| ----------------------------------- | -------------------------------- | --------------------------------- |
| Function call                       | Wrong args, missing params       | Parameter names, destructuring    |
| Object spread/merge                 | Property shadowing, missing keys | Spread order, key names           |
| Serialization (JSON, pino, etc.)    | Lost properties, type coercion   | What fields are included/excluded |
| Process boundary (spawn, IPC)       | Stdout parsing, buffering        | Line handling, JSON parse         |
| Async boundary (Promise, callback)  | Timing, unhandled rejection      | await, error propagation          |
| Error boundary (try/catch)          | Swallowed errors, wrong re-throw | Catch scope, error transformation |
| Framework boundary (Next.js, React) | SSR/CSR mismatch, lifecycle      | Rendering context, hydration      |
| Library boundary (pino, express)    | Config behavior, version quirks  | Library docs, default options     |

5. **Document the complete pipeline** with file paths and line numbers.

Use the Explore agent or direct file reads to map this pipeline. Read every file in the chain. Do not skip any step.

### Phase 3: Trace Forward with Concrete Values

**Goal:** Predict the exact value of the relevant data at every point in the pipeline.

Now reverse direction. Start at the entry point with a concrete example value (from the user's bug report or a representative case).

1. **At the entry point**, write down the initial value/shape of the data
2. **At each boundary**, predict what the data looks like AFTER the transformation
3. **Pay speci