Agent debugging often goes sideways when assumptions stay implicit. The agent sees a failing check, forms a theory, changes a file, and then keeps following that theory even after the evidence gets weak. An assumption log makes the reasoning visible before momentum turns into churn.
The log does not need to be formal. It can be a short working section in the run transcript or blocker report. The important part is that every assumption has a source, a confidence level, and a clear way to be disproved.
Write the guess before acting on it
A useful assumption log has three columns:
| Assumption | Current evidence | Disconfirming check | | --- | --- | --- | | The failure comes from generated indexes being stale. | A content file changed and the index timestamp is older than the edit. | Regenerate indexes and compare the diff before changing source code. | | The deploy problem is build-related, not routing-related. | The local build fails before any network request is made. | If the build passes locally, verify the live route before editing build config. | | The missing page is a content discovery issue. | The Markdown file exists but is absent from the generated JSON index. | If the index contains the slug, inspect route generation instead. |
This small structure slows down the first guess just enough to keep it testable. It also gives reviewers a map of why the agent chose one probe instead of another.
Convert stale assumptions into stop signals
The most useful line in an assumption log is the one that says when the assumption is no longer valid. Without that line, an agent can keep repairing around the same theory after the facts have changed.
Good runbook language sounds like this:
Before making a second fix for the same failure, update the assumption log. If the current action does not have direct evidence, or if the disconfirming check already failed, stop and report a blocker instead of expanding the diff.
That instruction creates a natural circuit breaker. The agent can still investigate, but it must keep its theories attached to observations.
Keep the log public-safe and portable
Assumption logs should avoid private implementation details. Describe the class of evidence, not sensitive identifiers: “the generated index omitted the slug” is usually enough; exact local paths, account names, internal hostnames, and raw secrets are not needed.
For reusable automation, the best assumption logs are boring. They show what was believed, why it was reasonable, what was checked, and what changed after the check. That is enough to make debugging reproducible without turning the report into a private incident dump.
Rule of thumb: if an agent cannot name what would prove its theory wrong, it is not ready to edit around that theory.