Decision Node

What Decision is and why it matters

Decision is the control node that determines where execution goes next. It exists so routing logic is visible in the graph instead of hidden in prompts or custom scripts. In mature NodeFox workflows, Decision nodes define the policy boundaries for confidence thresholds, quality acceptance, risk handling, retries, and escalation.

When teams struggle with explainability, Decision placement is usually the fastest way to restore control. If a branch cannot be explained by deterministic rules or clear options, that branch should be redesigned.

Execution behavior

Decision evaluates configured conditions or options and routes output through explicit branches. It can be used as a one-time gate or as part of a loop cycle with iteration bounds. Because routing is explicit, Decision outcomes are easy to inspect in run history and post-incident analysis.

For loop designs, Decision should own the convergence contract: what counts as pass, what counts as retry, and what happens when retries are exhausted.

Variants and configuration details

Basic variant

Basic is rule-driven deterministic routing and should be your default for policy logic.

Field	What it controls	Practical guidance
`Rules`	Ordered condition list (LHS / evaluator / RHS)	Keep rule order intentional because first-match behavior determines branch priority.
`OnPass`	Route mapping for matching rule	Use explicit route names that encode intent, not generic pass/fail labels.
`Max`	Maximum decision cycles before fallback	Always set for loop scenarios to prevent unbounded retries.
`Default`	Branch used when no rule matches or max is hit	Default should be deterministic and safe, not ambiguous.
`Slot`	Primary slot context for rule evaluation	Normalize payload shape upstream so slot references remain stable.

Rule shape and evaluator behavior

Each Basic rule is effectively:

LHS + Evaluator + RHS + OnPass

LHS: value to test (supports slot references like $1.status, $1.score)
Evaluator: comparison operator
RHS: expected value (literal value or slot reference)
OnPass: route mapping for the matching condition

Evaluator reference

Decision Basic supports these evaluators:

Evaluator	Typical use
`equals`	exact equality checks (`status == "approved"`)
`not equals`	explicit inequality checks
`contains`	substring or membership-style checks
`not contains`	explicit absence checks
`greater than`	numeric threshold gates (`score > 7`)
`less than`	numeric lower-bound checks
`greater than or equal`	inclusive numeric minimums
`less than or equal`	inclusive numeric maximums
`starts with`	prefix checks for structured string keys
`ends with`	suffix checks for extension or domain checks
`regex match`	pattern matching for advanced text validation

For reliable behavior, normalize data types before Decision evaluation (especially for numeric and boolean logic) so branches do not depend on implicit coercion.

Question variant

Question uses model-assisted evaluation for routing when deterministic rule sets are insufficient.

Field	What it controls	Practical guidance
`Question`	Natural-language evaluation prompt	Keep prompts narrowly scoped and pair with fallback controls.
`To`	Output slot for model answer	Separate answer output from pass-through business payloads.
`Pass From`	Input slot to preserve	Use for payload continuity across evaluation branches.
`Pass To`	Output slot for preserved payload	Keep mappings explicit to avoid silent payload loss.

Question variant should still terminate in deterministic routing semantics. For high-impact actions, use Question output as an input to a deterministic Decision/activation gate rather than directly authorizing side effects.

Use Question variant when semantic judgment is needed, but do not let it replace hard policy gates for high-impact decisions.

Options variant

Options is human-choice routing and is commonly used for approval or exception handling paths.

Field	What it controls	Practical guidance
`Options`	Human-selectable labels and destination routes	Keep options concise and action-oriented for fast operator decisions.
`from`	Source slot for routed payload	Pass only optional context to reduce accidental data exposure.
`to`	Destination slot mapping per option	Standardize option-to-slot conventions across teams.

Options is most effective when each option has a clearly documented operational meaning (Approve, Reject, Escalate, etc.) and a deterministic downstream path.

Loop and retry design

A safe retry loop looks like Conversation -> Decision -> (Pass branch or Retry branch) with a bounded Max and a deterministic fallback route. This fallback route should usually trigger either a review queue, structured failure output, or escalation handling.

If Decision loops are expensive, add run/cost instrumentation and review aggregate retry distributions. High retry density usually signals either weak prompts, weak acceptance criteria, or mismatched source data quality.

Common mistakes to avoid

The most common Decision mistake is putting critical policy logic inside Conversation instructions and then treating Decision as a cosmetic layer. Decision should be the policy source of truth. Another common issue is missing defaults, which can create ambiguous end states when none of the rules match.

For regulated or customer-impacting workflows, pair Decision with explicit approval identity capture and policy version references so branch outcomes are defensible.