Debug with testable hypotheses

Describe the failure before proposing a fix

A useful debugging request states expected behavior, observed behavior, and affected scope. Include the version, relevant input, and error. Remove credentials and private records from logs before you supply them to an AI tool.

“Export is broken” gives little direction. A better description is: “The export succeeds locally. In staging, the same manager request returns 403 after the latest deployment. Other routes still work.”

This description does not establish the cause. It identifies differences that can guide an investigation.

Keep several explanations available

Ask the agent for a small set of plausible causes and the evidence for each. Do not ask it to commit to the first convincing explanation.

For the fictional export failure, possible causes include a missing service identity permission, a changed role mapping, or a request sent to the wrong environment. Each explanation predicts different evidence.

The table is a starting point. A 403 response can originate from different layers. Identify which component produced it before assuming that application authorization failed.

Choose a safe observation

Start with an observation that can separate explanations at low cost. Compare the deployed version and non-secret configuration. Inspect the relevant error and request identifier. Reproduce the issue in an authorized test environment when possible.

Do not grant broad permissions merely to see whether the error disappears. That action changes the security boundary and can hide the actual missing permission. Do not paste a full production log into the model when a redacted error and request path are sufficient.

State what would weaken each hypothesis. This helps the agent revise its explanation instead of defending its first answer.

Change one cause at a time

After the evidence identifies a likely cause, make a focused correction. Avoid combining a permission change, a library upgrade, and a handler rewrite. If the symptom disappears, you would not know which change mattered.

Verify the original failure condition. Also check the neighboring boundary. If you correct access for a manager, confirm that an unauthorized user still receives a denial.

For a recurring defect, add a regression check at the layer that can detect it. A unit test cannot detect every deployment configuration error. Some failures need an integration check or a controlled post-deployment verification.

Stop repeated attempts without new evidence

An agent can generate many variations of a fix. More attempts do not necessarily improve the diagnosis. If the same failure repeats, ask what new observation the next attempt will provide.

Set a time or attempt limit for uncertain investigation. At that point, report the current evidence, rejected hypotheses, and unresolved question. This record lets another person continue without repeating the same experiments.

After recovery, record the cause and the condition that allowed it to reach the affected environment. A correction removes the immediate defect. A useful follow-up reduces the chance of the same failure returning.