Prefer deterministic action over indeterminate LLM action when possible
State: open/published
Summary
Section titled “Summary”- A captured workflow matures toward deterministic form (script, code) as its shape settles. LLM orchestration is the bootstrap form, not the destination. Whether a reoccurring workflow earns capture at all is P-0002-operationalize-activity’s call; this principle governs maturation from there.
- Workflows mature through five stages: conversation, prose skill, prose plus deterministic calls, deterministic workflow with explicit LLM tasks, generalized workflow with downstream hook points.
- The LLM plays four roles: conversational aid (Stage 1), orchestrator of under-defined work (Stages 2-3), explicit task executor (Stage 4), ambiguity resolver or reviewer (Stage 4 inverted).
- Recognize the stage. Premature determinization is its own anti-pattern.
Statement
Section titled “Statement”When a workflow or action can be expressed deterministically, as a script or code, that is the form it should ultimately take.
LLM orchestration is the bootstrap form of any workflow. It allows fast prototyping and tolerates fuzzy inputs and outputs. As the workflow matures, the surface the LLM touches directly shrinks in favor of deterministic mechanism.
Reliability
Section titled “Reliability”LLMs are stochastic. They drift from intent, hallucinate, and vary in how they execute a task. Harnessing reduces this but never removes it: the same prompt on the same input can give a different result, so a step whose correctness matters cannot be verified once and trusted after. A deterministic step can.
Expense
Section titled “Expense”LLMs are slow and expensive relative to code that does the same thing. They also regress in ways scripts do not: a prompt that worked yesterday can drift tomorrow without warning. For work that has settled into a known shape, that variability is pure downside.
How it applies
Section titled “How it applies”Natural progression: how workflows mature
Section titled “Natural progression: how workflows mature”A workflow passes through stages on the way from ad hoc to operationalized. Not every workflow reaches the end; whether one earns capture at all (the Stage 1 to 2 transition) is P-0002-operationalize-activity’s call. The rule here is to recognize the stage and not treat a Stage 2 prose skill as if it were a Stage 4 deterministic workflow.
| Stage | Form | What dominates |
|---|---|---|
| 1 | Manual instruction / user conversation | Free-form dialog; no shared artifact |
| 2 | Prose skill | A SKILL.md captures the workflow as natural-language instructions for an LLM to follow |
| 3 | Prose skill + deterministic calls | The skill still drives, but calls scripts/validators/CLIs for the parts that have hardened |
| 4 | Code or deterministic workflow with explicit LLM tasks | The orchestration is deterministic; the LLM is invoked at specific, narrow steps where its judgment is needed (or omitted entirely if not) |
| 5 | Workflow with downstream hook points | The Stage-4 workflow is generalized so downstream consumers can inject their own programmatic or prose steps at named lifecycle hook points without forking the workflow itself. Stage 4 + extension surface. |
Stage 4 is the shape the architecture points toward. Stage 5 is the composable shape that lets downstream consumers extend a deterministic workflow with their own deterministic or LLM steps. Reaching either is not a goal in itself; the goal is the progression. A workflow stuck at Stage 2 after its happy path has been stable for months is overdue for deterministic extraction. The Task entity reaches Stage 5 once its lifecycle and runner registry land.
LLM roles within the system
Section titled “LLM roles within the system”As the progression shrinks the LLM’s surface, its role shifts. Four roles fall out of the stages:
- Conversational aid. Stage 1. The LLM is a thinking partner in open dialog. The output is the conversation itself.
- Orchestrator of under-defined work. Stages 2-3. The LLM reads a
SKILL.mdand drives the steps: decides what to do next, calls tools, handles deviations. Most of today’s skills live here. - Explicit task executor. Stage 4. A deterministic harness calls the LLM for one bounded task (“summarize this”, “extract these fields”). Inputs and outputs are structured. The harness validates the result and decides whether to retry, fail, or accept.
- Ambiguity resolver or reviewer. Stage 4, inverted. The deterministic workflow does the work and consults the LLM only when it detects ambiguity, needs judgment, or wants a review of its output. The LLM is called rather than driving; that inversion is the shift from role 2.
Role 4 keeps LLM judgment without giving up determinism. Most workflows cannot be entirely deterministic, but they can be deterministic with judgment ports.
Examples
Section titled “Examples”solutions/ontological/lib/model/entities/task/ops/next.ts(sdlc task next): the deterministic tail of the pickup-order verb. The LLM head reads its output and presents it.sdlc entities validate: pure deterministic. No LLM in the validator path is a standing application of this principle./sdlc:task-ensure-ready: a Stage 3 skill. Prose drives, but it calls deterministic verifiers and returns pass or fail.- The Executable Task capability tree (C-0001 through C-0010): the target Stage 4 shape for the Task workflow.
Implications
Section titled “Implications”- This document is the canonical statement of the principle; downstream documentation reflects it.
- S-0004-sdlc-cli-llm-head-deterministic-tail crystallizes it for capabilities that take freeform input: the deterministic tail is the Stage 3 or 4 substance, the LLM head is the role 1 or 2 entry point.
- Likely future standards: a post-execution assessment shape (D-TQHZ-skill, proposed), per-skill stage classification, and enforcement of “no LLM in the validator path”.
- This principle does not say “rewrite everything in code”. It says recognize the stage and let the progression happen. A Stage 2 skill that has not seen enough use to know its shape stays at Stage 2.
P-0004-leverage-best-tool pulls the same direction from another angle: when an external tool has already reached Stage 4 for a workflow, swapping our Stage 2 skill for that implementation is the right move, even if our skill becomes a thin adapter.