← All Writing

ENGINEERING NOTES / AI-ASSISTED DEVELOPMENT

Before the Next Patch, Test the Explanation

A practical way to investigate AI-assisted debugging when a convincing answer hasn't fixed the problem.

Conceptual illustration of branching paths, with a blue route passing through an inspection window to a matching result.
Conceptual illustration

By Travis J. MacDonald ·

The first fix didn't work.

The AI explains why, adjusts the code, and tries again. That doesn't work either. Soon there are several changes, a longer explanation, and less certainty about what the original problem was.

I've written about the recurring mistakes AI agents make. This is one way I want to respond to them: before accepting another patch, ask what the previous attempt established.

If the answer is “nothing yet,” another implementation may be premature.

A useful investigation needs a claim, an observation that can challenge it, and a willingness to change direction. The AI can help with all three. I still have to notice when we are producing activity without learning anything.

Begin with an observable failure

Two pages connected across a sheet of glass, representing a mismatch between source and result.
Start with what you can observe.

“The page is broken” leaves a lot of room for interpretation.

“The revised heading is in the source file, but the local page still shows the old heading” is more useful. It identifies an expected result and an observed difference.

That difference becomes the thing to investigate. It also gives us a way to check whether a proposed fix addresses the original failure.

Without it, the task can quietly drift. The agent improves something nearby, a check passes, and the response announces success. Meanwhile, the heading that started the investigation is still wrong.

The observation doesn't need elaborate formatting. A URL, the expected behavior, the actual behavior, and the conditions needed to reproduce it may be enough.

A worked example: the heading that won't change

Three pathways diverge, with one illuminated path leading to an inspection point.
Follow the evidence through the alternatives.

Consider a constructed example, rather than an account of a particular client incident.

A developer edits a page heading. The local site continues to display the previous text. The AI suggests a browser cache problem and recommends refreshing.

That is plausible. It is one explanation among several.

Possible explanation A useful check
The browser is reusing an old response. Request the page outside that browser and inspect the returned content.
The route loads a different template. Trace the route to the file it actually renders.
The edited file is a build input. Check whether the served output was regenerated from that input.
The local request reaches a different running copy. Check which process and document root handle that address.

These checks answer different questions. None requires rewriting the page.

In this example, a fresh request outside the browser still contains the old heading. That weakens the browser-cache explanation. It doesn't rule out every cache elsewhere in the system.

Next, tracing the route shows that it serves a generated template. The developer edited the input, but the output hasn't been rebuilt.

Now the investigation has found a concrete mismatch: the changed file and the served file occupy different stages of the publishing process.

Regenerating the output through the project's existing build step produces a page containing the new heading. Requesting the original route confirms the revised content, and checking the rendered page confirms that it appears in the intended place.

The correction follows the evidence. There was no need to replace the template system, add cache-busting code, or redesign the page.

Notice what each check established

A question, an inspection, and a resulting page shown as three connected stages.
Each check answers a different question.

The useful part of that example is the narrowing of uncertainty.

The external request established that the problem wasn't confined to what the first browser displayed. The route trace established which template was served. Comparing input and output identified the missed generation step. Repeating the original request checked the result.

Skipping those distinctions makes it easy to claim too much.

“The request still shows old content” doesn't prove a particular build problem. Finding a generated file doesn't prove it is the one serving the route. A successful build doesn't prove the visitor sees the intended page.

Each observation supports a particular conclusion. Following that chain keeps us investigating the application in front of us instead of defending the first plausible story.

It also protects useful existing architecture. Before replacing a mechanism that appears to have failed, find out whether it was invoked correctly.

Ask for a prediction before another change

A debugging explanation becomes more useful when it predicts something we can inspect.

If the route uses a different template, we should be able to identify that template. If a conversion loses a field, we should be able to compare the field before and after that conversion. If an event fires twice, we should be able to observe the duplicate invocation.

A focused question for the AI is:

Before proposing another change, state the current explanation, the evidence supporting it, and the smallest check that would distinguish it from the strongest alternative.

That instruction doesn't make the answer correct. It makes the reasoning easier to examine.

Sometimes two explanations predict the same result. Then the proposed check won't distinguish them, and we need a better one. Sometimes a test fails for an unrelated reason. Then we need to understand the failure before treating it as evidence against the theory.

The point is to make the next action informative.

Include my own explanation in the test

A lens above two interlocking pieces, representing a closer look at an assumption.
Examine your own explanation too.

I may be the person who suggested caching.

If the AI expands that idea into a confident technical explanation, it can feel as though another investigator has confirmed it. That feeling can arrive before either of us has examined the route.

Anthropic's 2023 sycophancy study found that the assistants tested could favor agreement with users' stated beliefs over truthfulness. It gives me another reason to ask what independent support an agreeable answer adds. Towards Understanding Sycophancy in Language Models.

I can ask the model to challenge me. I can also accidentally make disagreement performative by insisting that it find something wrong.

The better request is to examine alternatives and say what the evidence supports. If my explanation survives, keep it. If another explanation fits better, change direction. If we can't distinguish them yet, identify the missing observation.

Being forceful in a conversation does not give my premise extra evidential weight.

Don't let the review inherit the conclusion

For a consequential change, I want a reviewer to see the original failure, the relevant code, the constraints, and the checks performed.

My diagnosis may belong in that package, but it should be labelled as a diagnosis. It shouldn't become an unquestioned premise.

A request to “confirm the cache fix” already narrows the review. A request to “check whether this change resolves the stale-heading failure and whether we identified its cause correctly” leaves room for a more useful finding.

A reviewer might discover that the visible symptom disappeared while the underlying process remains unreliable. It might find that the change works only for one route. It might agree with the diagnosis and identify a missing regression check.

That is useful scrutiny. Agreement between reviewers is still something to weigh alongside their evidence.

Keep the investigation small enough to use

This process should reduce wasted work.

I don't need a formal report every time a label is wrong. I do need to stop repeating an unproductive approach when the result gives us reason to question it.

The effort should increase with the consequences. A reversible local display issue may need a few observations. A data migration needs stronger evidence about preservation, failure handling, and recovery.

A practical investigation note can be short:

  • Failure: what should happen, and what happens instead.
  • Current explanation: the suspected cause and supporting observations.
  • Next check: what it could tell us.
  • Result: what happened and how that changes the explanation.
  • Accepted correction: what changed and how the original failure was checked.

That note helps the next person, including my future self, avoid starting from the first guess again.

Make the next attempt teach us something

An illuminated path winds through a maze toward the horizon.
Let each attempt guide the next.

AI can produce another patch quickly. That speed is valuable when the direction is sound, and expensive when it lets a weak explanation survive several more attempts.

After a failed fix, I want to know what we learned. Which possibility became less likely? Which assumption needs revisiting? What is the next observation worth making?

Sometimes the answer will justify another code change. Sometimes it will send us back to the route, the data, the requirement, or the original reproduction.

Before the next patch, test the explanation.