Start with the observed failure
Describe what the user sees, what they expected, when it started, and the smallest reliable reproduction. Include the exact route, input, account or role, environment, and timestamp when those details matter. Screenshots help with appearance; they do not prove which layer is wrong.
The first goal is not to fix anything. It is to turn a report into an observable condition. If the failure cannot be reproduced, say that clearly and gather the next best evidence: logs, network responses, stored values, or a before-and-after comparison.
Inspect the contract before the implementation
Many bugs are mismatches between layers. A database stores a percentage but the API expects a fraction. An endpoint returns a nullable value but the UI assumes a string. A deployment is pointed at a different branch than the developer tested. The code may be internally consistent and still wrong at the boundary.
Trace the value or action across the system: source data, transformation, API response, client mapping, rendering, and user interaction. Ask where the meaning changes. This is usually more productive than reading every file that contains a familiar variable name.
- What is the source of truth?
- What shape and units cross each boundary?
- Which environment and version produced the result?
- Where is the first point the observed value becomes wrong?
Write the hypothesis before the patch
A good hypothesis has three parts: the likely cause, the evidence that supports it, and the observation that would disprove it. For example: the UI is displaying a percentage as a fraction because the API boundary stopped normalizing the source value; compare the raw source, API payload, and rendered value to confirm.
This gives AI a productive role. It can identify the smallest set of files to inspect, suggest a targeted experiment, and draft a patch that addresses the boundary. If the evidence does not fit, the hypothesis changes before the code does.
Make the smallest safe correction
Once the cause is supported, patch the narrowest owner of the behavior. Avoid broad refactors during a bug fix unless the existing structure makes the correction unsafe. A small diff is easier to review, test, revert, and explain to the person waiting on the fix.
Ask AI to show the proposed diff and name the behavior it changes. Then inspect neighboring callers, types, validation, and error paths. A one-line fix can still be wrong if it moves a conversion to the wrong layer or changes another consumer’s contract.
Verify at the user-facing boundary
Run the narrow test first, then the relevant broader checks. If the issue is visual or interactive, use a browser check or screenshot. If it is an API contract, assert the exact response. If it is a data transformation, compare known fixtures before and after. The proof should match the failure, not just the file that changed.
Report the boundary of the proof precisely: local test passed, preview verified, production deployed, or customer-visible result confirmed are different statements. AI can help draft the report, but the evidence still has to come from the actual environment.
A reusable debugging prompt
When you need help, give AI this shape: ‘Observed behavior: __. Expected behavior: __. Reproduction: __. Environment: __. Relevant contract: __. Evidence already gathered: __. Do not edit yet. First identify the most likely boundary and state a hypothesis that could be disproved.’
That prompt changes the interaction from guess-and-patch to inspect-and-prove. It is a small habit with a large effect on debugging quality.