when AI coding agents scope before they're ready

You hand an AI coding agent a user story. Within seconds it has produced a scope document: what's in, what's out, which files change, which don't. It looks thorough. Then implementation starts and halfway through you realise the agent made a load-bearing assumption — about the API shape, about which existing component to reuse, about whether this feature touches the payment flow at all — that is simply wrong. The code is written. The worktrees are checked out. Reversing costs more than the original task.

This is the premature-commitment failure mode. The scoping stage completed, but it completed without the information it needed. The agent filled the gap with a confident-sounding inference instead of surfacing a question.

why agents scope confidently by default

Language models are trained to produce coherent, complete output. A scoping prompt that says "decompose this story into tasks" will get a decomposition. If the story is ambiguous — "add dark mode support to the settings screen" without specifying which settings screen, which components apply the theme, whether this is CSS variables or a separate stylesheet — the model will resolve the ambiguity itself. It will choose the interpretation that produces the most coherent plan. That interpretation may be wrong.

This is not a hallucination problem in the usual sense. The agent is not making up facts. It is doing exactly what it was asked to do: producing a scope. The problem is that "produce a scope" and "produce a correct scope" are different instructions, and the second requires knowing when you don't have enough context to proceed.

A well-prompted agent can be taught to ask questions. Most practitioners discover this and add instructions like "before scoping, ask clarifying questions about anything ambiguous." That helps. It also generates a wall of questions on every task, including simple ones where no clarification is needed. The model doesn't know the difference between a question worth asking and a question that wastes the developer's time.

how teams typically handle it

Three patterns emerge in practice.

Front-load the story. Write user stories with enough detail that the agent has nothing to infer. Define the API contract. Name the components. Specify the edge cases. This works, but it relocates the cognitive load from the agent to you. You're now doing the scoping before the scoping stage. For simple tasks it's efficient; for complex ones it's the same effort as just writing a spec by hand.

Structured specification templates. Require agents to fill a fixed schema before scoping: goals, constraints, affected files, out-of-scope items, open questions. The open-questions field is the critical one. If the agent is required to enumerate what it doesn't know, it surfaces ambiguities that a free-form decomposition would hide. This is closer to the right shape. The gap is that it's still the agent deciding what to treat as an open question — and confirming its own answers, rather than surfacing them to you before committing.

Manual review before implementation. Read the scope document before advancing. Catch the wrong assumptions yourself. This works and is the correct backstop, but it makes the developer the quality gate on every task rather than letting the tool surface the specific decisions that need a human answer. It's manual what should be instrumented.

the three mechanics that change the dynamic

The gap across all three patterns is the same: there is no mechanism for the agent to say "I can scope everything except this specific question, and I need your answer before I continue." The agent either proceeds or asks everything. What's missing is selective, structured surfacing of genuine unknowns — distinct from the overall scope output, actionable before implementation starts.

Three mechanics address this at different points in the scoping flow.

Open questions in the Intel pane. When the scope agent encounters a genuine unknown — a decision that can't be resolved from the codebase or the story as written — it surfaces that question explicitly in the scope UI rather than filling it with an inference. The developer sees the question before the scope is approved, not after implementation has already started on the wrong assumption. The question is specific and tied to the scope item it affects: not "is there anything else?" but "this item assumes the user settings store is in localStorage — confirm or specify the actual store."

Drag-to-reclassify. A scope document has an in-scope list and an out-of-scope list. Agents are conservative about including items they're uncertain about — they'd rather mark something out-of-scope and avoid the complexity. The developer reviewing the scope may disagree: that "out of scope" item is actually critical to the task. Without a reclassify mechanism, the only option is to reject the scope and restart the stage. Drag-to-reclassify lets the developer move items between in-scope and out-of-scope directly in the UI, without rerunning the scope agent from scratch. The scope document updates in place and the stage advances from the corrected version.

Freshness signals. On a long scope pass — one covering a complex story across multiple files and dependencies — early scope items may become stale by the time the agent finishes the later ones. A new dependency found late in the pass might affect an item that was scoped early. Without a signal, the developer sees a flat scope document with no indication of which items were informed by later findings. A freshness signal surfaces items that were updated or refined after the initial pass at the top of the Intel pane, so the developer's review focuses on what changed, not on re-reading the entire document.

what this prevents

The three mechanics target the same root failure at different points. Open questions prevent the agent from treating unknown-context as if it were known. Reclassification prevents a single wrong call from requiring a full stage restart. Freshness signals prevent late-pass refinements from being buried in a document the developer already read.

Together they change the scoping stage from a black box that produces a plan to a structured dialogue where the agent surfaces exactly what it doesn't know. The developer doesn't have to write a more detailed story upfront or read the entire scope document to find the load-bearing assumption. The tool does the work of flagging the specific decisions that need a human answer before implementation starts.

This matters more at scale. A task running three or four parallel implementation agents on a bad scope assumption doesn't just waste one agent's work — it wastes all of them, and the coordination cost of reconciling the diverged work is worse than starting over. The earlier the scope is correct, the less downstream correction is required.

the right stage for this

Scope clarification is one part of a broader set of stage integrity problems in multi-agent workflows. The analogous failure at the implementation stage is an agent that writes code in a scope it doesn't own; at the review stage, it's a reviewer that modifies code instead of flagging it. Each stage has a class of premature action that can be caught earlier with the right instrumentation.

For teams running parallel Claude Code agents, scope correctness is the highest-leverage point in the pipeline. Errors caught at scoping cost a conversation; errors caught at review or release cost a full pipeline run across multiple agents.

defract's 1.0.0 release ships these three scoping mechanics as part of the lifecycle's scope stage. Open questions, reclassification, and freshness signals are how the scoping stage behaves by default — not a configuration you add on top of a raw Claude Code session. If you're running structured Claude Code workflows and want to see what a gated scope stage looks like in practice, it's a free download.