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

The most essential part of planning occurs before any task is created. When an agent encounters an underspecified goal, it either makes an assumption or asks a question. Asking a question costs only a single reply but changes nothing that has already transpired. Ordewell, a tool created by the author, implements this question step rather than a survey.

Changing a plan's goal is free, while editing a task is nearly free as no execution has taken place yet. Altering code that an agent has already written is costly, as it results in a diff, a verdict, and a review, and the underlying decision remains incorrect. The planner should address ambiguity before decomposing the plan, not after.

Planning agents should focus on facts and leave decisions to the user. Questions should be asked when the goal is vague or a decision could significantly affect the outcome, such as selecting a storage engine, library, scope, or API shape. A well-defined goal requires no questions at all. If a library and shape are already specified, the questioning step should be empty, allowing the planner to move forward with the plan.

One question at a time is recommended, rather than batching them. Each decision typically determines which subsequent questions are necessary, so answering one question at a time prevents guessing about undefined aspects. The planner should reference actual files when asking questions, providing both the evidence and a recommended option. If there is no user available, the planner will make the most reasonable assumption based on its research and incorporate it into the task description.

Before generating a structured plan, the planner creates a short prose outline, detailing the steps in order. The planner then transforms this outline into a fully structured plan, including dependencies, runners, models, and the effort required for each task. This two-step process allows the planner to catch any issues with decomposition, as correcting a mistake in prose takes only one reply, while fixing the same error in a paragraph of a structured plan can take multiple messages.

Questions can sometimes be a stall, causing the conversation to loop without making progress. To prevent this, the planner is equipped with a guard that avoids repeating the same read. However, even a well-formulated question might still be incorrect. The planner's recommendations, such as using sqlite for storing plan state, are based on research and should be treated as hypotheses rather than proven facts.

Finally, it's crucial to remember that the outline created using the question step is not a contract. The plan can still be edited after it's committed, so confirming the prose outline is merely a checkpoint, not a final lock. The plan remains editable, providing a strong checkpoint while maintaining flexibility.