Outcomes and Transitions
Where work moves when a run starts and when it succeeds, fails, is blocked or is closed: the start transition, stay, the seeded defaults, and the retry policy.
Preview. Stages 1.0 is built and merged but not deployed yet. Names, screens and defaults on this page can change before release.
A stage says where an issue goes next. Instead of a workflow that hard-codes tracker status names, each stage declares a target for the moment a run starts and for each way a run can end. The targets are stage keys, so the same configuration works against any tracker whose statuses you have mapped.
The five transitions
| Transition | When it applies | Target |
|---|---|---|
start | A run begins. For example, Development dispatched from Backlog moves the issue to In progress. | A stage key. Never stay. |
success | The card's obligations were met and its verdict, if it owes one, passed. | A stage key or stay. |
failure | The obligations were not met or the verdict failed, after retries for mechanical errors are used up. A review that requests changes lands here and is normally routed to a stage with the role rework. | A stage key or stay. |
blocked | The agent reports that it cannot continue. | A stage key or stay. |
close | The agent's result says the work should be closed instead of done, for example because it is obsolete or a duplicate. | A stage key or stay. Usually a stage with the role closed. |
blocked is separate from failure on purpose. A failure re-dispatches into the same situation that failed. Work that is blocked is better sent somewhere it will wait, such as a hold stage, so nothing keeps spending tokens against the same wall.
stay
stay means "leave the issue where it is". It is the target when you want an outcome to change nothing in the tracker. An outcome a stage does not declare at all also means stay. start is the one transition that must name a stage.
How a target becomes a tracker status
You name stages. The platform turns the target into the tracker's own status using the project's status mapping: the target stage's write status. It sends the resolved transitions with the run, and the runner applies the one that matches how the run ended. The runner holds no status names of its own.
If a target cannot be resolved for a tracker, the platform falls back to stay and logs a warning. Three things cause this: the target stage does not exist, it is disabled, or the tracker has no write status for it. Nothing fails. The issue stays put.
Transitions always come from the stage the issue was in when the run was dispatched, even after start has moved it on.
Transitions are carried on the run and applied by the runner. A runner build that does not understand them ignores the new fields and keeps its built-in status moves. Check that your hosts run a build that supports the stages wire before relying on stage outcomes to move issues.
Seeded defaults
The system stages ship with these targets. Any scope can override a single outcome without restating the rest.
| Stage | start | success | failure | blocked | close |
|---|---|---|---|---|---|
icebox | not set | stay | stay | stay | closed |
backlog | in-progress | review | rework | icebox | closed |
in-progress | not set | stay | stay | stay | stay |
review | not set | acceptance | rework | icebox | closed |
acceptance | not set | done | rework | icebox | closed |
rework | in-progress | review | stay | icebox | closed |
done | not set | stay | stay | stay | stay |
closed | not set | stay | stay | stay | stay |
Two defaults are deliberate:
- Blocked work in Backlog, Review, Acceptance or Rework goes to Icebox, a hold stage, so it is not picked up again until someone mentions a card on it.
- A failed Rework run stays in Rework. This stops a rework loop from bouncing between Rework and Review.
The previous SDLC template recovered blocked work to Triage. The system stages do not reproduce that, because Triage is not one of them. If you want it, add a Triage stage and point blocked at it.
An example override
An ops-style board has no separate acceptance step. At the project level, set Review's success to done:
Stage: review
On success, move to: doneThe rest of Review's outcomes still come from the system stage.
Retry policy
A stage can carry a retry policy:
| Field | Range | Meaning |
|---|---|---|
retries | 0 to 5 | How many times to retry a mechanical error. |
backoffSeconds | 0 to 3600 | How long to wait between attempts. |
Retries cover errors that are not the agent's fault: a provider error, a failure to spawn the agent, a worktree error, or a launch that was never acknowledged. Only when the retries are used up does the stage report failure or blocked. A mechanical failure is never counted as the agent failing the work.
Backlog, Review, Acceptance and Rework ship with two retries and 60 seconds of backoff. The retry policy is carried with the run and enforced by the runner.
What is not an outcome
Some endings are not outcomes, and none of them moves the issue to rework:
- no verdict was produced;
- an operator cancelled the run;
- a gate timed out.
In these cases the issue stays where it is and a comment is posted. CI, deploy, merge and human approval gates are preconditions of success, not outcomes of their own.
Edit a stage's transitions
Open the stage in Settings, then Stages, and choose Edit (or Customize first, for an inherited stage). The Outcomes section has one selector per transition:
| Selector | Transition |
|---|---|
| When a run starts, move to | start |
| On success, move to | success |
| On failure, move to | failure |
| When blocked, move to | blocked |
| When closed, move to | close |
Each offers the stages in your effective set, plus stay (leave it where it is) for every transition except start. Retries (0-5) and Backoff seconds (0-3600) set the retry policy; leave both empty to inherit it. The save is refused if a target is not a stage in the scope you are editing.
Because transitions use stage keys, adding a stage and pointing an outcome at it is a settings change. The workflow is untouched.