A Coding Agent Needs an Assumption Register Before It Acts

“Fix the slow export.”

For a developer, that sentence may carry years of context. For a coding agent, it can leave open the affected users, the acceptable latency, the data boundary, the intended target, the rollback posture, and whether the report still describes the current system.

An agent that fills every gap with a plausible default may look decisive. It is actually changing the task.

That is why an agent needs an Assumption Register before it acts.

Ambiguity Is a Boundary on Action

The UnderSpecBench preprint evaluates coding agents on benign but underspecified instructions. It separates ambiguity in intent clarity, target certainty, and blast radius, and evaluates outcomes such as wrong-target and overscope behavior in addition to ordinary completion. The study is a benchmark result, not a universal estimate of production behavior. Its design nevertheless makes one practical point clear: a successful-looking run can still have acted on an unstated premise.

The Ask or Assume? preprint studies clarification seeking on an underspecified software-engineering setting. It frames missing information as something an agent can detect before execution instead of treating execution as the only way to make progress.

The ICAE-Bench preprint studies a different interactive project-building setting that begins with fuzzy product requirements and uses a simulated user to reveal hidden constraints. Its benchmark design reinforces the narrower point that clarification and repository construction can be evaluated together without treating every initial request as fully specified.

These findings do not mean an agent should ask a person about every tiny detail. Excessive questions can make a tool feel unusable. The proposed framework uses this original editorial rule:

An unstated constraint must not quietly become a material decision, target selection, or authority grant.

An agent can inspect public task context, form a provisional interpretation, or prepare a reversible proposal. But it should preserve the difference between what the task stated and what it inferred.

The Assumption Register

The Assumption Register is a proposed, application-level record for ambiguity that matters to a later decision. It is not a hidden reasoning transcript, a substitute for approval, or a place to copy sensitive source material.

• Register element: Statement or unknown — Question it answers: What did the request explicitly say, and what is missing? — Why it matters: Keeps the task record from silently rewriting the requester’s intent.
• Register element: Classification — Question it answers: Is this a stated fact, evidence-supported inference, low-consequence working assumption, or material unresolved constraint? — Why it matters: Makes the consequence of uncertainty visible.
• Register element: Supporting basis — Question it answers: Which approved task context supports the interpretation? — Why it matters: Lets a reviewer distinguish an inference from a guess without retaining unnecessary raw content.
• Register element: Affected boundary — Question it answers: Which target, behavior, authority, data, compatibility, or effect decision depends on it? — Why it matters: Connects ambiguity to the decision it could distort.
• Register element: Allowed interim posture — Question it answers: May the agent inspect, draft, run a bounded check, wait, or ask? — Why it matters: Prevents uncertainty from automatically authorizing a consequential step.
• Register element: Resolution route — Question it answers: What evidence, decision, or authorized role would resolve it? — Why it matters: Turns “unclear” into a concrete next state.
• Register element: Expiry or invalidation — Question it answers: What later change would make the interpretation unsafe to reuse? — Why it matters: Stops an earlier assumption from becoming durable task truth.

The record does not need to be verbose. A one-line entry is enough if it answers the right question: what is assumed, why, what is allowed while it remains unconfirmed, and what would settle it?

Four kinds of uncertainty deserve different treatment

Not all missing detail deserves the same response.

• Kind: Stated fact — Example shape: The task explicitly names the requested behavior and intended target. — Suitable posture: Record it as a requirement, then check it against the current task state.
• Kind: Repository-supported inference — Example shape: Existing tests and public documentation consistently imply a local convention. — Suitable posture: Use it only within the stated evidence boundary and disclose it where it affects review.
• Kind: Low-consequence working assumption — Example shape: A formatting choice can be changed without changing behavior or scope. — Suitable posture: Proceed provisionally if it remains reversible and does not conceal a material product decision.
• Kind: Material unresolved constraint — Example shape: The request leaves the target, data boundary, irreversible effect, public contract, or success condition unclear. — Suitable posture: Ask, defer, or prepare an explicitly non-final proposal; do not silently choose.

This classification makes a useful distinction. “The existing adjacent tests use this naming style” can be a bounded inference. “The user probably wants this behavior applied to every account” is a materially different claim. They should not be handled the same way.

Questions Are One Resolution Path Within a Larger Model

An Agent’s Question Needs a Decision Contract concerns the structure of a question once the system must request information or a decision. The Assumption Register starts earlier: it decides whether an unstated detail may safely remain provisional.

That creates several possible outcomes:

• Register disposition: Supported — Honest agent behavior: Proceed within the recorded scope.
• Register disposition: Provisional and reversible — Honest agent behavior: Continue with limited inspection or a clearly labelled draft.
• Register disposition: Needs a decision — Honest agent behavior: Ask a bounded question that names the decision and its consequence.
• Register disposition: Needs evidence — Honest agent behavior: Gather permitted, relevant context before choosing an interpretation.
• Register disposition: Held — Honest agent behavior: Preserve useful work but do not advance the material step.
• Register disposition: Invalidated — Honest agent behavior: Revisit the assumption because the task, context, or policy changed.

The held state matters. The Coding Agents Don’t Know When to Act preprint evaluates 200 human-verified reports for which no code change is required and reports that agents can propose undesirable changes. It argues that inaction must be treated as a possible success path. For a task with an unresolved boundary, a visible hold is often more useful than a confident but ungrounded patch.

A small illustrative register

Suppose a task says: “Make exports faster for the analytics team.”

The agent might record:

• Assumption: “Analytics team” names a known product area, not a user group with a separate entitlement model. — Classification: Repository-supported inference — Affected boundary: Target and data scope — Interim posture: Inspect relevant public task context; do not change access behavior. — Resolution: Confirm if the request implies an entitlement change.
• Assumption: The slow path is a server-side generation step rather than the download interface. — Classification: Material unresolved constraint — Affected boundary: Technical target and success criterion — Interim posture: Gather bounded performance evidence; do not claim a fix yet. — Resolution: Reproduce a permitted scenario or ask for the failing path.
• Assumption: Output order is unchanged unless explicitly requested. — Classification: Low-consequence working assumption only if existing behavior is observable — Affected boundary: Compatibility — Interim posture: Preserve current order in a draft design. — Resolution: Revalidate if tests or product requirements indicate a deliberate ordering change.

The point is not that these exact interpretations are right. The point is that they are visible enough to challenge before they turn into a broad implementation.

Make the boundary visible before the agent narrows it

Ambiguity often disappears from a task record because an agent makes an early choice and later describes that choice as if it were a requirement. The register prevents that rewrite.

When a material unknown remains, the agent should state:

1. what is unknown;
2. which decision it prevents;
3. which low-risk work can continue, if any;
4. what information or authority would resolve it; and
5. whether the current task should be held.

This produces better questions, but it also improves review. A reviewer can see whether the agent made a fair inference, stayed within a reversible boundary, or needs the task owner to choose.

Keep the Register Minimal and Privacy-Preserving

An Assumption Register should retain the minimum useful summary. It does not need raw chat history, credentials, private URLs, hidden prompts, or copied source payloads. A reference to an authorized task artifact and a plain-language statement of the uncertainty are usually enough.

It should also avoid false precision. A confidence number without an evidence boundary can look scientific while conveying very little. The useful facts are the assumption’s source, consequence, allowed posture, and resolution condition.

A practical adoption path

1. Identify one type of coding-agent task where a wrong target or unapproved scope would be costly.
2. Define a short list of material boundaries: target, user-visible behavior, authority, data handling, compatibility, and external effects.
3. Require the agent to classify each missing boundary before it proposes a consequential step.
4. Allow reversible inspection and drafting only when the register says why they are safe.
5. Treat a decision request or held task as a valid outcome when evidence cannot resolve the ambiguity.
6. Review completed tasks for assumptions that later proved wrong, then refine the boundary definitions.

The goal is not to make an agent hesitant. It is to make it honest about where the task ends and its inference begins.

A general lesson for coding agents

For ambiguous coding work, an assumption is not harmless background context. It is a potential decision. The Assumption Register is a proposed educational framework for making that decision bounded, reviewable, and reversible where possible. It does not describe a released Virillio Code feature.

Sources and further reading

• Coding Agents Are Guessing: Measuring Action-Boundary Violations in Underspecified DevOps Instructions — The UnderSpecBench preprint varies intent clarity, target certainty, and blast radius in benign underspecified coding-agent tasks, then evaluates boundary violations as well as completion in its studied configurations.
• Ask or Assume? Uncertainty-Aware Clarification-Seeking in Coding Agents — A preprint evaluates clarification seeking on an underspecified SWE-bench Verified variant and separates uncertainty detection from code execution in its studied setting.
• ICAE-Bench: Evaluating Coding Agents as Interactive Project Builders — A preprint treats fuzzy requirements, clarification, tool use, debugging, and repository construction as an interactive coding-agent setting.
• Coding Agents Don’t Know When to Act — The FixedBench preprint studies 200 human-verified reports for which no code change is required and treats inaction as a possible success outcome.

Editorial disclosure

This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.