Make coding agents show their assumptions before they edit

I think autonomous coding agents need a visible, editable assumption ledger before they start changing code. The dangerous step is often not the patch; it is the quiet jump from an ambiguous request to a confident interpretation. By the time a reviewer sees the diff, that interpretation may already be spread across several files and tests.

Each entry could state the assumption, its source (ticket, existing code, or agent inference), an uncertainty level, the affected files or systems, and simple approve/reject controls. This would be a lightweight bridge between requirements and diffs, not a transcript of every model thought.

I can also see it becoming paperwork that people reflexively approve, or an extra interface that anchors reviewers on the agent’s framing. Would a ledger genuinely improve safety and collaboration in your workflow? Please share examples of agent mistakes caused by hidden assumptions, and whether you would actually use one.

The affected-systems field is the part I’d care about most. An assumption that looks harmless in one module can become a compatibility decision once it touches a queue, schema, or external API. I’d want the ledger generated before tool execution, not reconstructed afterward from the diff.

This seems useful as a hypothesis, but I’d be careful about claiming improved safety without a study. The control may improve visibility while still failing if reviewers approve everything by habit. A small trial comparing review outcomes would tell us more than enthusiasm or annoyance.

I’d make the default experience brutally short: show only assumptions that change behavior, permissions, or scope. If every inferred variable gets an entry, users will learn to skip the whole thing. The product question is whether it saves more attention than it consumes.

For security-sensitive work, “source: existing code” is not enough. Existing code can encode the vulnerability the agent is extending. I’d want explicit uncertainty around trust boundaries, data handling, and authorization assumptions, with rejection blocking execution when the risk is high.

I’d use it for migrations and auth changes, probably not for renaming a local variable. Scope matters. A universal ceremony will lose; a ledger that appears only when the agent detects ambiguity or blast radius has a chance.

The approve/reject wording matters. “Approve” can feel like endorsing the whole implementation, when the user may only be accepting one interpretation. Maybe each assumption needs “accept,” “edit,” and “ask me,” so disagreement stays cheap.

This is a design document with better timing and worse branding. That is not necessarily an insult. Put it in the place where the mistake is still cheap to fix, and keep it from turning into another permanent pane nobody reads.

The operational edge case is stale assumptions. Requirements change while an agent is working, and a previously approved interpretation may no longer apply. Each entry should show when it was made and be rechecked if the affected system or ticket changes.

I’m not convinced visibility alone solves anchoring. A neat ledger could make reviewers less likely to challenge the assumptions because the agent has already presented a coherent story. The comparison should be against careful review, not against blindly accepting a raw diff.

I’d also record rejected assumptions, at least until the change is merged. Otherwise the agent can circle back to the same interpretation through another path. That history could be more valuable than a long explanation of why the accepted choice seemed reasonable.

The distinction between evidence and inference should be visually obvious. A ticket statement, a repository convention, and a model guess are not equivalent sources. If they share one confidence badge, the ledger may create false precision rather than clarity.

Enterprise teams would ask for retention, permissions, and auditability immediately, which could make this heavy fast. I’d start with a local, review-scoped artifact attached to the proposed change. Prove it helps developers first; governance can follow if there is a real signal.

For small teams, the best version might be one sentence: “I assumed refunds are allowed after shipment; this changes billing and order state.” That is enough to catch a costly misunderstanding without introducing a new process everyone has to maintain.

There’s a privacy angle too: the source field could expose sensitive ticket text or internal context unnecessarily. The ledger should reference evidence with access controls rather than copying every underlying detail into a broadly visible artifact.