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

PartYAMLNotes
Modecontrol.modeFirst 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 labelcases[].label1–3 words shown on graph edges and badges. Unique, 32 characters or fewer
Choose this whencases[].whenThe condition (below)
Then activatecases[].activateSteps to start when it matches
Instructionscases[].instructionsOptional: what the agent does when this outcome is chosen
Run bycases[].run_byOptional owner for the outcome’s instructions
Otherwisecontrol.otherwise.activateRequired 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

ConditionYAML when.nameMatches whenFields
JudgedjudgedAn LLM judges a yes/no question you writequestion (≤ 255 characters)
Output equalsoutput_equalsA step output field equals a valueref, value
ExpressionexpressionA comparison of references is true, for example {{steps.size.output.prs}} <= 1expr
All checks succeededall_checks_succeededEvery check so far passed—
PR review passedpr_review_passedThe review agent approved the PR—
PR mergedpr_mergedThe PR was merged—
Step output validstep_output_validA step’s outputs match their declared fieldsstep
Child runs roll upchild_run_rollupEvery 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:

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

    Type to search the docs, help center and blog.