> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# How a run works

> What happens when a run's plan does not work: a fresh planner writes a new version, each failed check, escalation or evidence gate spends one of the run's attempts, and a person takes over when they run out.

A run plans, changes the code and checks the change, as [Planning before any code changes](/guides/starting-and-following-a-session#planning-before-any-code-changes), [Changing the code, within the plan](/guides/starting-and-following-a-session#changing-the-code-within-the-plan) and [Checks](/guides/starting-and-following-a-session#checks) describe.
This page covers what happens when that first plan does not hold.

## When the plan does not work: re-planning

### What starts a re-plan

A re-plan starts in three cases:

* A declared check fails on a run that has a plan.
* The [evidence gate](/guides/starting-and-following-a-session#the-evidence-gate) fails on a run that has a plan, for example a criterion has no evidence. The fresh planner is given the failing items.
* The agent escalates because a step cannot be done as written, needs a file the plan does not name, or is too large for one context.

A run with no plan, because none could be made, does not re-plan.
A failing check or evidence gate goes back to the agent, as [Checks](/guides/starting-and-following-a-session#checks) and [The evidence gate](/guides/starting-and-following-a-session#the-evidence-gate) describe.

### What the fresh planner sees

A new planner starts, and it does not continue the old one.
It is given:

* the previous version of the plan,
* the failed check, the escalation or the failing gate items, with a one-line summary of each, and for a check the end of its output,
* the change made so far, as its changed files and its diff.

It is never given the agent's conversation or the earlier planner's.
It can read files in the sandbox to look at anything the diff cuts short, and it cannot change one.

It writes a whole new version of the plan.
The agent then carries on from the new version, starting at the first step the new version adds, so steps already carried out are not run again.
A new version has to keep every step already carried out and add at least one step after them, because the steps carried out are not run again.
A version that only rewrites an earlier step, or that drops a file an earlier step changed, is refused and counts as no new plan.
If the plan cannot be corrected without a person deciding, or the planner records no usable new version, the run waits on you.
The detail after the reason says which of these happened, and for a failing check the session shows the agent's last message, as [When the agent cannot fix a failing check](/guides/starting-and-following-a-session#when-the-agent-cannot-fix-a-failing-check) describes.

### When a new version would break a limit of your request

Every version of the plan is checked against the limits of your request before the agent works from it, not only the first.
That includes a version made when the agent sends the work back partway through a step, and one a fresh planner makes after a failed check or evidence gate.
When a new version would break a limit, such as a schema change when migrations are not allowed, a new dependency when dependencies are not allowed, or a file you told it not to touch, the planner asks you first, as [When the planner asks you first](/guides/starting-and-following-a-session#when-the-planner-asks-you-first) describes.
The session shows **Waiting on you** with the reason **A question from the planner**, a detail that names the limit, such as "a constraint is in the way: migrations are not allowed", and the question.
The agent does not work from that version, and nothing it would have changed is written.
The changes made before it stay in place while the run waits and after you answer.
The question itself spends no attempt; the failed check, failed evidence gate or escalation that started the re-plan counts as one, as [Attempts](#attempts) describes.
To answer, write in the message box of the session: a fresh planner plans the next version from your answer, and the run carries on from the changes already made.
If your answer still needs the change the limit forbids, the planner asks again and the run keeps waiting, with the changes made so far in place.
Asking again after you answered spends one attempt; with none left, the run waits with the detail **out of attempts** instead.
A new version that stays inside every limit is recorded and built without asking.

### Attempts

Every failure spends one of the run's attempts: as many as your project's [Attempts setting](/guides/project-settings#attempts-and-review) gives it, 3 unless an admin changed it, shared with the review's send-backs, as [Rounds and attempts](/guides/review#rounds-and-attempts) describes.
A failing check spends one, a failed evidence gate spends one, an escalation spends one, and a review that sends the change back spends one.
A failure that is both, such as a failing check that also leaves the gate failing, spends one attempt and not two.

Re-planning has no limit or setting of its own.
It follows a failure, and the failure has already spent its attempt.
With three attempts, a run re-plans at most twice: the third failure leaves none, and the run does not re-plan.

### When the attempts run out

When a check or the evidence gate fails, or the agent escalates, and no attempt is left, the run does not re-plan.
It becomes **Waiting on you** with the detail **out of attempts**.

* For a failing check the reason is **The checks fail and need you**.
* For a failed evidence gate the reason is **Evidence gate failed**.
* For an escalation the reason is **The plan did not cover this**.

Your reply in **Send a message** starts a new turn, and the run carries on from it as [Changing the code, within the plan](/guides/starting-and-following-a-session#changing-the-code-within-the-plan) describes.

### Every version is kept

Each new version adds a line to the conversation, such as **Plan changed to version 2: A check failed**.
The line ends with **View version 2**, which opens that version of the plan above the conversation.
There, **Why this version** says what started it, with the failed check, the escalation or the failing gate items in one line, and **See version 1** opens the version before.
The Plan panel shows the same **Why this version** for whichever version you pick in its **Version** list.
Earlier versions stay readable, and the plan the agent is working from is the latest one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.