In this categoryTroubleshooting · 27

API Errors & Auth

Tokens & Context

Cost & Reliability

TroubleshootingIntermediate

How to Ask an Agent to Explain a Bug Before Fixing It

Make the agent state the root cause first so you can confirm the diagnosis before it writes a fix that masks the real problem.

7 minIntermediate

Agents are quick to patch symptoms. Ask one to fix a failing test and it may silence the test rather than fix the bug behind it. Requiring an explanation of the root cause before any edit lets you catch a wrong diagnosis early and avoid a fix that just hides the problem.

What you need

A reproducible bug or failing test
An agent session in the project
About 6 minutes

Step 1: Ask for the cause, not a fix

Tell the agent to diagnose first and hold off editing. You want the root cause in plain words before any code changes.

Agent - diagnose first

You

The cart total is wrong for discounts. Explain the root cause first. Do not edit anything yet.

Agent

The discount is applied after tax instead of before. The order of operations in calcTotal() is reversed. That is the cause; no fix written yet.

Root cause before any edit.

Step 2: Confirm the diagnosis

Check the explanation against the symptom. A right cause explains every part of the bug; a wrong one leaves something unexplained.

Watch for symptom patches

If the proposed cause is something like the assertion is too strict, push back. Loosening a test or clamping a value usually hides the bug rather than fixing it.

Step 3: Approve the targeted fix

Once the cause is confirmed, ask for the smallest fix that addresses it and a test that would have caught the bug.

prompt

Diagnosis confirmed. Fix calcTotal() to apply the discount before tax, and add a test that fails on the old order. Keep the change minimal.

Add the test that catches it

Pair every root-cause fix with a test that fails on the old code. That proves the diagnosis was right and stops the bug from quietly returning.

Result: fixes target the actual cause instead of muting symptoms, and a new test locks the behavior in so the bug stays fixed.

Watch related tutorials