The Debugging Ladder: How Deep to Go Before Calling For Help

Year one of heavy agent use I escalated too fast. I would paste a failing test into Claude, fail to fix it in two tries, and post to a forum. Year two I have a mental ladder that keeps me from wasting either my time or anyone elses.

The Ladder

1. Read the error message carefully
2. Read the failing code carefully
3. Read the tests or caller carefully
4. Bisect what changed
5. Ask the agent with full context
6. Check the library docs
7. Read the library source
8. Ask a human

Most bugs die between steps one and four. The agent at step five is a tool, not a crutch. Steps six and seven find the deep ones. Step eight is reserved for the small set that survive everything else.

Why Step One Catches Most

Error messages lie less than anyone thinks. The pattern is not that the error is wrong. The pattern is that we stop reading at the first unfamiliar word. A Python traceback has seven lines of context. Reading all seven fixes most of my bugs in under a minute.

The Bisect Step

Step four is underrated. If the code worked an hour ago and does not work now, something between then and now caused it. Git bisect or just scrolling git log --oneline usually finds the commit in five minutes.

git log --oneline --since='2 hours ago'

Most of my debugging at step four is rolling back one commit at a time.

The Agent Step

When I escalate to Claude, I bring the full context: error message, failing code, relevant caller, and what I have already tried. Agents without context produce average advice. Agents with full context produce specific, correct advice about eighty percent of the time.

The Library Source Step

Most consultants never read library source. Opening a node_modules file or a site-packages file feels like breaking a rule. It is not. Library source is the ground truth when documentation lies or lags. I keep a mental list of libraries whose source I have actually read: it grows slowly, but each entry saves me hours over the next year.

When to Ask a Human

Humans go at the end of the ladder, not the start. Human time is expensive on both sides. I reserve human questions for bugs where I can show them everything the ladder produced and still have a real question. Those questions get real answers.

Julia Evans has written the single best collection of debugging zines I know of.