Before the plan

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

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.

A plan is cheap to change before it runs

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.

Facts are the agent's job, decisions are yours

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.

One question at a time

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.

When there is nobody to ask

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.

The outline before the JSON

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.

Honest limits

• Questions can be a stall. An agent that keeps asking for confirmation is not making progress. The conversation loop carries a guard against a planner that repeats the same read instead of answering, but a badly prompted planner will still prefer asking to deciding.
• A grounded question can still be wrong. The agent recommends sqlite because it found a database folder. That is research, not proof, and a confident recommendation is the easiest kind of wrong answer to accept.
• Nobody has to answer well. Approving an outline without reading it is allowed, and it moves the same mistake one step later. The step only helps if you treat it as the last cheap moment.
• It costs a round trip. On a small, clear job the whole exchange is overhead a single prompt would have skipped. That is what the no-questions-when-the-goal-is-clear instruction is for, and it is a judgement the planner makes, not a guarantee.
• The outline is not a contract. A plan can still be edited after it is committed, so confirming the prose is a checkpoint rather than a lock. It is a strong checkpoint because the plan is still editable, not because the plan is final.

Source and design notes

The question step as described, in the code and in the skill that ships with it: the planner's instructions, the conversation loop, the grilling skill, and github.com/ordewell/ordewell.