Prefer deterministic action over indeterminate LLM action when possible

Status: open/published

Summary

• Captured workflows mature toward deterministic expression (script, code) as their shape crystallizes; LLM orchestration is the bootstrap form, not the destination. When a reoccurring workflow earns capture at all is P-0002-operationalize-activity’s call — this principle governs maturation from there.
• Workflows will naturally mature through five stages: conversation, prose skill, prose+deterministic, deterministic with explicit LLM tasks, generalized 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/reviewer (Stage 4 inverted).
• Recognize the stage. Premature determinization is its own anti-pattern.

Statement

When a workflow or action can be expressed deterministically (a script or code execution), that is the form it should ultimately take.

LLM orchestration is the bootstrap form of any system or workflow. It allows fast prototyping and supports ambiguous, fuzzy inputs and outputs. Maturation of the system, component, or workflow involves shrinking the bounds LLM tools touch directly in favor of more deterministic mechanism.

Why

Reliability

LLMs are stochastic at their core, leading to intention drift, hallucinations, and task execution variability. Proper harnessing alleviates some of this, but ultimately

Expense

LLMs are slow and expensive relative to code functions that perform the same thing. They are also subject to regression in ways scripted tools are not: a prompt that worked yesterday can drift tomorrow without warning. For substance that has crystallized into a known shape, that variability is pure downside.

The principle is not “no LLMs.” It’s “the LLM’s job changes as the work matures.” Treating LLM orchestration as a bootstrap layer rather than the destination keeps the system honest about which parts have hardened and which haven’t.

How it applies

The natural-progression model below describes how a single workflow typically matures; the four-role classification describes what the LLM is doing at each stage.

Natural progression: how workflows mature

A workflow typically passes through stages on the way from ad-hoc to operationalized. Not every workflow makes it to the end; some are too rare or too fuzzy to be worth operationalizing, and that’s fine — whether a workflow earns capture at all (the Stage 1→2 transition) is P-0002-operationalize-activity’s threshold to call. The principle here is to recognize the stage and not pretend a Stage-2 prose skill is already 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 “more ideal state” the architectural philosophy points toward; Stage 5 is the composable shape that lets a deterministic workflow grow downstream consumers for deterministic and LLM based extensions and customization. Reaching either for a given workflow is not a goal in itself; the goal is the progression. A workflow stuck at Stage 2 when its happy path has been stable for months signals overdue deterministic extraction. This principle takes over after capture: it governs how far and how fast a captured workflow hardens (Stage 2→5). It does not set the capture threshold — that is P-0002-operationalize-activity.

Stage 5 is the realization of “task is appropriately generalized with lifecycle hook points for injection of downstream/consumer programmatic or prose steps”, the planned shape for the Task entity once its lifecycle and runner registry land (see the task-kinds-and-runners ADR).

LLM Roles Within the System and SDLC

As the progression compresses the LLM’s surface area, the LLM’s role shifts. Four distinguishable roles can be extracted from the stages above:

1. Conversational aid. Stage 1. The LLM is a thinking partner in open-ended dialog. No commitment to a workflow; the output is the conversation itself.
2. Orchestrator (for under-defined workflows). Stages 2-3. The LLM reads a SKILL.md and drives the steps. It decides what to do next, calls tools, handles deviations. This is where most of today’s plugin lives.
3. Explicit task executor. Stage 4 (when applicable). The LLM is called by a deterministic harness for a specific, bounded task: “summarize this”, “extract these fields”, “draft this section.” Inputs and outputs are structured. The harness validates the result and decides whether to retry, fail, or accept.
4. Ambiguity resolver / reviewer. Stage 4, inverted. The deterministic workflow does the work; the LLM is consulted only when ambiguity is detected, when judgment is required, or as a reviewer of the deterministic output. The LLM is called rather than driving; the inversion is the key shift from role 2.

Role 4 lets the system retain LLM judgment without giving up determinism. It’s the architectural shape that earns the right to be at Stage 4: most workflows can’t be entirely deterministic, but they can be deterministic with judgment ports.

Examples

• plugin/lib/model/entities/task/ops/next.ts (the sdlc task next verb): deterministic tail of the task pickup-order verb. The LLM head reads its output and presents to the user.
• plugin/validators/validate_frontmatter.ts: pure deterministic. No LLM in the validator path is one of this principle’s standing applications.
• /sdlc:task-ensure-ready: a Stage-3 skill: prose drives, but it calls deterministic verifiers and returns pass/fail.
• The Executable Task capability tree (C-0001 through C-0010): describes the target Stage-4 shape for the Task workflow.

Implications

• This document is the canonical statement of the principle. Downstream documentation reflects it; the project’s README carries the user-facing one-liner (“Deterministic by default; LLM-orchestrated where it has to be”) as the short reflection of what is captured here in full.
• Standards that crystallize from this principle:
  • S-0004-sdlc-cli-llm-head-deterministic-tail: LLM-head / deterministic-tail split for capabilities that take freeform input. The deterministic tail is the Stage-3/4 substance; the LLM head is the role-1/2 entry point.
  • Likely future standards: skill post-execution assessment shape (see docs/planning/decisions/D-TQHZ-skill.md); per-skill stage classification; “no-LLM in the validator path” enforcement.
• ADRs that apply this principle: the sdlc-cli/ ADR’s tail/head split is a direct application. The principle is the canonical source of the idea; the ADR is how it lands in a specific design.
• This principle does NOT say “rewrite everything in code.” It says recognize the stage and let the natural progression happen. A Stage-2 prose skill that hasn’t accumulated enough use to know its shape should stay at Stage 2. Premature determinization is its own anti-pattern.

Notes

Related: leverage best tool. P-0004-leverage-best-tool pulls in the same direction from a different angle: when an external tool has already reached Stage 4 for a workflow, swapping our Stage-2 skill in for that implementation is the right move, even if our prose skill becomes a thin adapter. P0004 is the canonical statement; this section notes the interaction with the natural-progression model above.

---

← Back to Principles