Ask first: the questions a planner asks before it writes the plan

A developer building Ordewell, an Apache 2.0 planning tool, argues that AI coding agents should resolve ambiguity by asking one grounded, evidence-backed question at a time before decomposing a goal into tasks, since a wrong assumption baked into a plan fans out into expensive code changes. The tool instructs planners to look up facts themselves, ask only about decisions that materially change the outcome, and, in one-shot runs with no user, write the assumption into the task description so it is reviewable.

The most useful part of planning happens before any task exists. A goal arrives underspecified, the agent reads the code, and then it either guesses or it asks. The guess becomes ten tasks built on a decision you never made. The question costs one reply and changes nothing that has already run. Disclosure: I build Ordewell, so this is the question step as it works in my tool rather than a survey of the field. It is free and Apache 2.0. The reasoning stands without installing anything. Everything in a plan is expensive in proportion to how far it has travelled. Changing a sentence in the goal is free. Editing a task in the plan is nearly free, because no session has executed it yet. Changing the code an agent already wrote is the expensive one, and it is expensive in the way that matters: you now own a diff, a verdict and a review, and the underlying choice it was built on is still the wrong one. That is the whole case for the question step. Ambiguity that costs one sentence at the start costs a rewritten task later, and a decision that fans out into dependencies costs several tasks. So the planner is told to resolve ambiguity before it decomposes, not to produce a plan and let you correct it afterwards. The rule that keeps the questions short is a split of responsibility. Anything that can be looked up is looked up. Which router the project uses, where the config lives, whether a dependency already exists: those are facts, and a question that asks you for one of them is a question the agent should have answered by reading the repository. What is left is the part that is genuinely yours. The planner is instructed to ask when the goal is vague or when a decision would materially change the outcome, and the examples it is given are exactly the forks that are not recoverable later: which storage engine, which library, how wide the scope is, what shape the API takes. The same rule cuts the other way. A clear, fully specified goal needs no questions at all. If you have already named the library and the shape, the questioning step should be empty and the planner should get on with the plan. Questions are not a ritual. Batching questions feels efficient and is not. A decision usually determines which questions are worth asking next: answer the storage question one way and the migration question changes, answer it another way and the migration question disappears. A list of five questions written before the first answer is a list where four of them are guesses about a world you have not described yet. So the instruction is one question per message, no numbering, no second question tacked onto the end, and then stop and wait. It is slower to read and faster to finish, because it does not walk you through questions that only existed under an assumption you were about to correct. ❓ Where should plan state be stored? sqlite / a json file next to the repo / a server I found a db/ folder and a migration runner, so I would use sqlite unless you want the plan to be readable and diffable by hand. ➡️ sqlite, migrations in db/migrations Questions also have to be grounded. The planner is told to reference actual files, so its question arrives with the evidence that produced it and a recommendation attached. A question with no file behind it is not clarify, it is a survey, and you can answer it by asking the agent to go read something. Some runs have no user in them. A one shot run is told the opposite of the interactive rule: there is no one to answer, so where the request is ambiguous it makes the most reasonable assumption grounded in its research and writes that assumption into the task description. Writing the assumption down is the part worth copying even if you never touch the tool. An assumption recorded next to the task it shaped is reviewable at the moment you read the plan. The same assumption held silently is discovered later, in a diff, by whoever has to work out why the code does what it does. Answering the questions does not hand you a finished plan. The planner first writes a short prose outline: the slices, in order, in plain sentences. Only after you confirm that outline does it turn it into the structured task plan, with dependencies, and runners, models and thinking effort per task. Two steps where one would do, on purpose. The outline is where you catch a wrong decomposition, and decomposition is the decision with the longest shadow: a plan with the boundaries in the wrong places fails one task at a time for an hour before anyone can see it. Correcting the same mistake in a paragraph of prose takes one reply. The question step as described lives in the planner's instructions https://github.com/ordewell/ordewell/blob/main/packages/core/src/services/PlanPrompts.ts , the conversation loop https://github.com/ordewell/ordewell/blob/main/packages/core/src/services/PlannerConversation.ts and the grilling skill https://github.com/ordewell/ordewell/blob/main/skills/grilling/SKILL.md that ships with the tool. Ordewell turns one goal into an ordered, editable plan of coding agent tasks, each with its own runner, model and mode, and treats a task as done only when its completion marker shows up in that runner's output. Source: github.com/ordewell/ordewell https://github.com/ordewell/ordewell . Free, Apache 2.0, no paid tier.