zfinix/aster/plan-and-present

Plan and present

1. Read before you write a word of it. Open every file the plan will

change, not just their names, and trace who calls the functions you will touch. When the plan picks a library or leans on one, read the parts of its source you depend on. 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. "main.rs or wherever the commands live" in a plan means you stopped reading too early. Stay read-only until they answer.

1. The plan is a file you build up, not a message you compose at the end.

Write a skeleton with write_plan as soon as you know the shape of the work, then fill each section in as you read. When a finding changes your mind, edit that section with old_str/new_str. The draft is where you think; the approval is where the user reads the result.

1. Settle the forks before you write them down. A choice that is genuinely

the user's (scope, a trade-off with no right answer in the code) goes to ask_user first, and the plan records what they chose. Do not leave the decisions as a list of questions at the bottom.

1. Write these sections, in this order:

• ## Context: what is true today and why the change is needed. Every

claim about the code cites path:line. This is how the user checks that you are aimed at the right problem.

• ## Decisions: each choice, the evidence behind it, and the alternative

you rejected with a real reason. When reading the code reversed your first idea, say so and show what reversed it. That is the most useful paragraph in a plan.

• ## Changes: per file, the functions that change and what changes in

them, plus the existing code you will reuse instead of writing new. Specific enough that someone else could carry it out.

• ## Risks: migrations, deletions, rewrites, published artifacts,

anything touching credentials, and what you are still unsure of. If something is irreversible, it also goes in the first line of Context.

• ## Verification: the exact commands to run and the result each should

give. "Run the tests" is not verification; cargo test -p aster-cron schedule with the cases it must cover is.

1. Scale it to the work, never below the evidence. A subsystem earns a

long document. A three-file fix earns short sections. Short is fine; vague is not. Every section still names real files and real commands.

1. Name the decisions, not the steps. "Split the device-code flow out of

provider.rs:212 before touching the token store, because both backends call it" is a decision. "Implement OAuth" is a step, and a step is what the user already asked for.

1. `update_plan` is the progress strip, not the plan. Its steps track what

is done while you work. The document wins the approval, then the approved work becomes update_plan steps, kept current through completion.

1. 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.

1. A rejection is information, not a retry. Edit the sections they

objected to and present again. Do not re-send the same plan with the objection unaddressed, and do not narrow the plan just to get a yes.