The fork everything turns on
A change that decides something is planned before it is built. A change that decides nothing is built directly. That single question is what splits the path in Which route your change takes, so it is worth being able to answer it yourself before you type anything.
Planning writes no code. It reads, it asks, it checks what it concluded against the code, and it leaves a written plan behind.
What counts as deciding something
A decision is a request with two real routes and no obvious answer, where the choice changes the scope, the cost, or what a person ends up seeing. A modal or a separate page. Extending the flow that already exists or adding a second one. This service or that one. Something that comes out one way for one record and another way for the next, where nobody has said which rule applies.
Which of two things you meant is a decision too, but only when they behave differently — two buttons that submit different things, two screens that show different records. Two candidates that differ only in where their code lives are not a decision: there is nothing for you to choose, and it gets resolved by reading.
A fact nobody wrote down is not a decision. How the current flow behaves, what an existing screen already shows, whether something is reused anywhere else, what the project's conventions say — those have answers, and the answers are looked up rather than put to you. A question about a fact that reading could settle is a question that should not have been asked.
Two more things that are not decisions, however technical they sound: where the code goes, and how it is written. A plan says what has to happen and in which states, not which file holds it. The standards decide the rest.
A technical choice is a decision when the risk, the cost or the proof turns on it. Handling a payment provider's notices in the order they arrive or in the order they were sent, keeping a long task on the screen or moving it to the background: those are asked while you plan, with the rest, and the answer is recorded with the other answers. A technical choice nothing turns on is still not put to you.
What it asks you, and how
The ambiguity that decides what gets investigated is settled first: what you actually want, and what problem is being solved. That one is asked at the start, because everything after it depends on the answer.
Everything found afterwards is gathered and put to you together. The whole scope arrives at once and is confirmed once — the behavior, the states it has to tell apart, what must not change, how it will be proved, and the technology at the level of "a modal" or "a form" rather than a list of files. You correct a piece of it and only that piece is re-proposed; the rest is not walked again from the top.
Real decisions come to you as questions. Missing facts do not come to you at all. And when a later check turns up several things at once, they arrive in one message rather than one at a time.
Before the questions reach you, the plan is swept for what it leaves undecided. Besides the states, the permissions and what ships with the change, that sweep looks at four things your request rarely names on its own: the other places the same thing happens — every way a record reaches the state you are changing, every screen that shows it, every kind of person it applies to; two mechanisms that reach the same person or record, and what happens when both apply; what points at the thing being changed or removed; and the flow that already does nearly the same, and whether this one should behave like it. Only places that really share the state your change alters count. Last, it reads each point of the plan as whoever builds it would, and anything they would have to ask you joins the same questions. Each question comes with what turns on the answer and the answer it recommends.
Questions stay inside what you asked for. A question about an area nobody mentioned is not a clarification — it is a second request you never made — so something unrelated noticed along the way is named in a line at the end, to be picked up in its own thread, rather than turned into a question or quietly absorbed into your change.
What you approve is checked before it is written down. Every claim the plan makes about how the system behaves today is verified against the code that would have to hold it: that a flow being reused actually accepts your case rather than merely existing, that a name proposed for something new is not already used on that screen for something else, that a shared behavior being changed was traced to everyone who consumes it. What that check finds either gets resolved silently or comes back to you as a finding first and a question second.
What you see before it is built
When your change adds or alters something a person sees, the scope comes to you with a drawing: the screen as it looks today and as it would look. The one of today is drawn from the real screen, with its real data, and checked against it before you see it — a screen with nothing on it is drawn empty and says so. The one of tomorrow is drawn with your product's own components and styles. When your product's design already settles how it should look, you get one proposal; when the design is new or has more than one way to go, you get several to choose from. You pick one or ask for changes, and approving the scope approves that design.
The drawing appears in the conversation when your assistant can show it there, and otherwise as a page saved outside your repository whose location you are given. Only the approved one is kept, beside the plan and with sample data, never the real data of today's screen. It is what the build aims at and what the browser check compares the finished screen with. A change small enough for the direct route, described below, is not drawn.
What it leaves behind
A written plan, saved in your project's analysis/ folder in the toolkit so it outlives the conversation that produced it — numbered by the server, tagged with the branch you planned it on, and listed in the folder's index. You read it in the Projects section; nothing is added to your repository and nothing is committed for it. See Your projects and their documents. It says what the problem is and where it shows, what the investigation established, what must happen and in which states, why it is worth doing, what must not change, the questions that were asked with the answers they got, and how the result gets proved. Unless the change took the direct route, described below, it ends with a technical plan: where the change runs, what already exists and serves, what clashes, where the code strays from the standards, and the risks to watch for — the order a provider's notices arrive in, data that already exists, how a line fits on a narrow screen. It names modules and files to find one's way, never the code to write.
Underneath it is a checklist — one row per thing the plan promised — that moves from pending to done or blocked as the work actually happens. Whoever picks the task up later reads that rather than guessing how far it got.
Before it is saved, you are asked whether to leave it waiting or mark it ready to run. Ready puts it in the queue the toolkit works through; waiting leaves it as a document you can hand to the build step whenever you want.
A decision your project keeps taking is offered to its vision. When a decision you confirm has already been settled the same way by three earlier plans, and it is a product decision — who the product serves, how it speaks, how consistent it has to be, what it will never do, how things are named, what comes first — the plan is followed by a question: does that answer belong in the project's vision? It names the question, the answer that keeps coming back and the earlier plans that gave it. Say yes and it tells you which part of the vision it belongs to and what to write there, for you to record with /vision; planning never writes into the vision itself. Once the answer is in the vision, later plans read it and stop asking. Say no and that occurrence is dropped.
The build step follows it instead of improvising. Decisions recorded in the plan are treated as settled and are not reopened halfway through, which is the whole point of taking them once. The technical plan is the exception, and by design: it is guidance, followed while the code agrees with it, and where the code turns out different the build decides, records what it found in the plan and keeps going, without stopping to ask you — unless the correction would change what the plan asks for. The one thing that sends a plan back is the code refuting something the plan argued from — then the run stops and returns it here, because everything decided on top of that claim was decided from something untrue, and no single answer repairs that.
When it is not worth it
A request that decides nothing does not need any of this. Wording on a screen, a spacing, a colour, the order two elements sit in, an existing component put where another one was — you already know what you want and there is nothing to choose. Planning it would buy you a conversation and one more document, and change the result not at all.
The direct route still checks the thing you named actually holds what you said, and still searches for anywhere else it is read before touching it. What it skips is the investigation, never the proof: the analyzer still runs, and anything you can see is still opened in a browser.
When in doubt, plan. Sending a small change through planning costs one conversation nobody needed. Sending a real one straight to the build step ships a decision nobody looked at.
Next
- Which route your change takes — the four kinds of change, and where this one fits.
- How do I ask for a change — the whole path, with the diagram.
- What each command does — the planning command beside the other fifteen.