plan-and-present

Plan and present

1. Research before you write a word of it. Read the files you are going to change, not just their names. A plan written from a guess about the code is the expensive kind of wrong: the user approves it, and the first edit finds out. Stay read-only until they answer.
2. The plan is a document, not a table of contents. exit_plan_mode takes markdown and the user reads it before deciding. "Stage 1: auth crate" tells them nothing they did not already know; it is a label for work you have not described. Write the work itself.
3. Cover, in whatever order the change wants: what you are going to do and why; the files and functions you will touch, by path; the approach you chose and the one you rejected, with the reason; what you are unsure of; how you will know it worked. A user who disagrees should be able to point at the sentence they disagree with.
4. Scale it to the work. A subsystem earns a page with headings. A three-file fix earns a few paragraphs. Padding a small change into a long document wastes the reader, and both fail the same way: the user cannot tell which parts you actually thought about.
5. Name the decisions, not the steps. "Split the device-code flow out of provider.rs before touching the token store, because both backends need it" is a decision. "Implement OAuth" is a step, and a step is what the user already asked for.
6. Flag anything irreversible or outward-facing up front. Migrations, deletions, rewrites, published artifacts, anything touching credentials. If the plan contains one, say so in the first section rather than in passing.
7. update_plan is the progress strip, not the plan. Its steps track what is done while you work. Never present that list as your plan: it is short labels by design, and standing it in for the document is what makes an approval unreadable.
8. Present once, then stop. Call exit_plan_mode and wait. No edits, no state-changing commands, no "starting on this while you read". The user's answer is the point of asking.
9. A rejection is information, not a retry. Fold what they said into the document and present it again. Do not re-send the same plan with the objection unaddressed, and do not narrow the plan just to get a yes.