Debugging

Debugging with your agent: see the root cause

Your agent found the bug and wrote five paragraphs about it. How to get the root cause shown on the lines, with the timeline of what happened, so you can confirm it.

Your agent found the bug. Its explanation is five paragraphs long, names six files, and ends with a fix. It might be right. You cannot tell without redoing the investigation yourself.

A root cause is an argument

A good root cause explanation is short and checkable:

1. The symptom. What someone saw, and when.
2. The surprise. The one line that does the wrong thing.
3. The evidence. Why that line explains the symptom, and nothing else does.
4. The fix. And why it removes the cause, not just the symptom.

Timing bugs need a timeline

Many real bugs are about order: two requests racing for one balance, a cache expiring for everyone at once, a queue filling faster than it drains. A paragraph about a race is very hard to check. A timeline of it is easy.

deck lets your agent show you a root cause that way. The code sits beside a small page the agent draws, like two cash-outs landing on one wallet milliseconds apart. As each sentence is read, its line lights up and the timeline moves forward, until the money is missing. The next group shows the fix replaying the same moment.

Confirm before you merge

When the cause is shown on the lines, confirming it takes a minute. When it is not, you either trust it or redo the work. Ask your agent to show you before you accept the fix, and ask what it could not verify. That part is the most useful thing to read.