Decide and outcomes
Branch a workflow with a Decide step: outcomes, conditions (judged questions, outputs, expressions, checks), targets, Otherwise and first or all matches.
On this page
A Decide step chooses which steps run next. It holds a list of outcomes. Each outcome has a condition (“Choose this when”) and the steps it starts (“Then activate”). If no outcome matches, the Otherwise branch runs. Steps on branches that weren’t chosen are skipped and show “not this route” in the run.
A typical use is sizing work: small changes go straight to implementation, larger ones get a spec and an approval first.
Anatomy of a decision
| Part | YAML | Notes |
|---|---|---|
| Mode | control.mode | First match (first_match): outcomes are tried top to bottom and the first that matches wins. All matches (all_matches): every matching outcome’s targets run |
| Outcome label | cases[].label | 1–3 words shown on graph edges and badges. Unique, 32 characters or fewer |
| Choose this when | cases[].when | The condition (below) |
| Then activate | cases[].activate | Steps to start when it matches |
| Instructions | cases[].instructions | Optional: what the agent does when this outcome is chosen |
| Run by | cases[].run_by | Optional owner for the outcome’s instructions |
| Otherwise | control.otherwise.activate | Required fallback targets |
In the graph, edges from a decision carry the outcome label, and the Summary view shows the question with a chip per branch (for example Small · Otherwise). A branch that ends without more steps reads “End the run”.
Conditions
| Condition | YAML when.name | Matches when | Fields |
|---|---|---|---|
| Judged | judged | An LLM judges a yes/no question you write | question (≤ 255 characters) |
| Output equals | output_equals | A step output field equals a value | ref, value |
| Expression | expression | A comparison of references is true, for example {{steps.size.output.prs}} <= 1 | expr |
| All checks succeeded | all_checks_succeeded | Every check so far passed | — |
| PR review passed | pr_review_passed | The review agent approved the PR | — |
| PR merged | pr_merged | The PR was merged | — |
| Step output valid | step_output_valid | A step’s outputs match their declared fields | step |
| Child runs roll up | child_run_rollup | Every child run of a Repeat for each succeeded | — |
Writing judged questions
The deciding agent reads the question and the run’s context, then answers yes or no. Write questions a careful reviewer could answer from the evidence:
- “Is this one PR or less, with a low blast radius?”
- “Does the stack trace point at code in this repository?”
- “Is the bug cosmetic, with a workaround?”
Avoid compound questions (“Is it small and safe and documented?”); use separate outcomes or an expression on structured outputs instead.
Structured conditions are cheaper and more predictable
Output equals and Expression don’t call a model, so they cost nothing and always give the same answer for the same data. Pair them with a Transform or a step that declares typed outputs:
- id: classify
kind: transform
name: Classify the alert
owner: { kind: agent, agent: builder, model: sonnet-5.5 }
instructions: Extract the fields below from the input.
input: "{{trigger.alert.title}}"
outputs:
- { key: severity, type: enum, values: [low, medium, high], required: true }
- id: route
kind: decide
name: Route by severity
owner: { kind: orchestrator }
control:
mode: first_match
cases:
- id: high
label: High
when: { name: output_equals, ref: "{{steps.classify.output.severity}}", value: high }
activate: [hotfix]
- id: medium
label: Medium
when: { name: output_equals, ref: "{{steps.classify.output.severity}}", value: medium }
activate: [plan]
otherwise: { activate: [file-issue] }Targets
“Any step that doesn’t run before this one can be a target; picking one makes it start directly after this step.” Targets must also be turned on. A step can be the target of several outcomes; its edge label then lists them, such as Small · Otherwise.
When you add an outcome with Add outcome, Duun creates the outcome and a blank target step in a new lane, so you can fill in what that branch does.
First match or all matches
- First match suits routing: one path per run. Order outcomes from most specific to most general.
- All matches suits fan-out: for example, run a security review and a performance review when both apply. Every matching outcome’s targets start; Otherwise runs only if none match.
Validation
The editor checks decisions as you edit. These problems block Apply:
| Problem | Message |
|---|---|
| Outcome without a label | ““Size & route” — case 1 needs a label.” |
| Label too long | “Case 1 label must be 32 characters or fewer.” |
| Duplicate label | “Another outcome already has this name.” |
| Judged without a question | ““Size & route” has a judged case with no question — a run that reaches it fails.” |
| Question too long | “Case 1’s question is over 255 characters.” |
| Empty expression | “Case 2 needs an expression.” |
| Output equals without a ref | “Case 2 needs an output to compare.” |
| Step output valid without a step | “Case 3 needs a step to check.” |
| No targets | ““Size & route” — Small has no destination.” |
| Invalid target | ““Plan” can’t be a target: it runs before this step or is off.” |
| No Otherwise | “Every condition needs an otherwise — pick at least one fallback stage.” |
A second Decide step is a warning, not an error: “This already decides once. Add an outcome to that decision instead.” Two decisions are allowed, but one decision with more outcomes is easier to read and test.
Testing branches
In a test run, Force outcome lets you pick which outcome each decision takes (Auto lets the decision run). Use it to walk every branch once before you turn the workflow on.