Should coding agents keep an assumption ledger?

I use coding agents, and I’m increasingly convinced that every nontrivial change needs a visible assumption ledger: what the agent inferred, which requirements were ambiguous, what evidence it used, and what still needs a human answer. Passing tests only shows that the implementation works against the chosen interpretation—not that the interpretation was right.

This matters most in unfamiliar or legacy repositories. “Add retry handling” could produce clean, well-tested code in a billing service while quietly violating an undocumented rule that charges are one-shot. I’d like to see a compact ledger attached to the pull request and updated whenever the agent revises its plan, rather than burying the reasoning in chat logs.

But mandatory documentation can become wallpaper. Should this be required for every substantial agent change, or reduced to an “uncertainties and confirmations” section? Disagree, share workflow examples, or suggest a better mechanism.

I’d make the ledger append-only for plan changes, but keep it brutally small. Three unchecked assumptions are useful; a transcript of every repository search is not. The important distinction is between evidence and confidence theater.

The billing example is exactly where this earns its keep. Product language like “retry” often hides a policy decision. I’d want the agent to surface that ambiguity before touching code, not merely document it afterward.

I’m persuaded by the traceability argument, but not yet by “mandatory.” The brief evidence for better outcomes is still limited, and documentation has a real maintenance cost. A useful experiment would compare compact ledgers with ordinary PR descriptions.

Security review has the same failure mode: the code can be locally correct while the inferred threat model is wrong. I’d require explicit statements about trust boundaries and unverified assumptions, at least for auth, payments, and data access changes.

My fear is checkbox compliance. If the agent fills in “assumed existing behavior is unchanged” on every PR, reviewers will stop reading. Maybe require a ledger only when the agent detects ambiguity or changes its plan.

The presentation matters as much as the content. Put unresolved assumptions near the top of the PR, with a clear request for confirmation. If people have to open a separate agent log, they probably won’t.

This sounds like a changelog for guesses. Useful, provided it stays shorter than the change itself. Otherwise we’ll create another ceremonial document everyone claims to value and nobody reads.

I’d include operational assumptions, not just code ones: fallback behavior, alerting, migration timing, and who owns the exception path. Legacy systems usually fail at those edges, where the ticket is least specific.

A ledger can also create false reassurance. An agent may list the right uncertainty and still make the wrong call. Human confirmation should be a blocking state for high-impact assumptions, not just another paragraph in the PR.

Plan revisions are the key part for me. The final diff hides discarded approaches, and those discarded approaches often reveal the original ambiguity. I’d preserve only decision changes, not every intermediate thought.

For organizations, attaching it to the PR is easier to govern than inventing a separate system. But I’d want configurable thresholds; treating a typo fix like a payment-flow change will make the control meaningless.

I’d be careful about the “evidence” field if it includes sensitive repository context or copied user data. A concise reference to the relevant file, test, or requirement is safer than dumping agent conversation into a permanent record.