--- name: workflow-fit-and-tuning description: Decide whether a process should be a spur workflow at all, tune an accepted one for latency and observability, keep its nodes inside the simplicity budget, and refactor across the boundary — promote a descriptive procedure into YAML, demote a YAML back to prose, or optimize one in place. see_also: - spur-cli - operations - authoring-workflows --- # Workflow Fit & Tuning Three questions that sit **before and around** the mode gate: 1. **Fit** — should this be a `spur workflow` at all, or a descriptive procedure / checklist? 2. **Tuning** — given it is one, how is it configured for low latency and legible traces? 3. **Refactor** — how do you move a process across that boundary in either direction? **Polaris:** get things done with high efficiency, low latency, and observability. A workflow that does not beat prose on all three is prose with a YAML tax. --- ## 1. Fit gate — workflow or prose? Run this **before** the [mode-selection gate](operations.md#sub-procedure-mode-selection-gate). The mode gate answers *which kind of workflow*; it presumes an answer to *whether* — and that presumption is the more expensive one to get wrong. ### What each side actually buys | | `spur workflow` YAML | Descriptive procedure (skill reference, slash command, checklist) | | --- | --- | --- | | Buys you | Durable run record, resumable HITL pause, bounded retry loops, machine-readable terminal status, `trace`/`--follow`, `cancel`/`clean`, unattended `--async` | Judgment at every step, zero authoring ceremony, edits are one-line, no subprocess per step | | Costs you | Authoring + `validate`/`dry-run` upkeep, one subprocess per action node, indirection an agent must read through, a definition that rots when the surface moves | Nothing is replayable, nothing is recorded, "what happened on that run" is unanswerable | | Fails at | Steps whose outcome only a reader can judge | Anything that must run the same way twice, unattended | ### The three-part test A process earns a workflow only when **all three** hold: - **Replay** — it runs repeatedly, unattended, or across different operators. - **Branch** — at least one step routes on a *machine-checkable* predicate (exit code, JSON field, file present), and the run may retry or gate on it. - **Record** — someone will later need to answer "what happened on run X" from persisted evidence. Three yes → author the workflow. Two → borderline: prefer prose plus one shell script, and revisit when the run count justifies it. One or zero → **descriptive procedure**; say so and stop. ### Signals | Signal in the described process | Read as | | --- | --- | | "Retry until the gate passes", "loop until clean" | workflow — bounded loop is the engine's job | | "Pause for approval, continue later / in another session" | workflow — HITL resume needs a run record | | "Every night", "for each task in the batch", unattended | workflow — replay + record | | "Then check whether it looks right and decide" | prose — the predicate is judgment, not an exit code | | "It depends what the diff says" | prose — the branch has no machine-checkable condition | | Runs once, then the situation has changed | prose — a checklist, not a definition | | One operator, in-session, watching each step | prose — the trace has no second reader | ### The two anti-patterns - **Prose wearing YAML.** Every node is an `agent.run` with a raw prompt, edges are all unconditional. The engine adds a process spawn per node and contributes no branching, no gate, no retry. This is the ADR-069 R2 measure firing on *every* node — the advisory is telling you the whole file is misplaced, not that eight prompts need polish. Demote it. - **YAML wearing prose.** A skill reference that says "then run the checks, and if they fail fix and re-run, up to three times" — a bounded retry loop written as a paragraph an agent re-interprets every session, with no record of how many attempts actually happened. Promote it. ### Hybrid is the usual answer The boundary runs *through* most processes, not around them. Keep judgment in the skill or slash command; put the deterministic gate loop in the workflow; let the workflow's judgment steps call the command by name. That is the ADR-043 preference restated as an architecture: **the workflow selects and orders capabilities, it does not contain them** (ADR-069). --- ## 2. Tuning — latency, efficiency, observability ### Cost model — know what you are spending | Node / element | Real cost | Consequence for design | | --- | --- | --- | | `agent.run` action | A full agent session: seconds to minutes, plus tokens | **The dominant cost.** Count them; every one you remove is the largest single win available | | `shell` action | One `sh -c` subprocess, milliseconds | Cheap individually — but each node is also a persisted transition round-trip | | Guard (`kind: shell`) | One subprocess **per evaluation**, re-run on every loop iteration | A loop with a bound of 5 pays its guards 5 times | | Loop `iterationBound` | Worst case = bound x per-iteration cost | It is a **latency ceiling**, not only a runaway safety net | | HITL pause | Unbounded wall-clock (waits on a human) | Never put one inside a loop body | ### Latency checklist - [ ] **Fewest `agent.run` nodes that still do the work.** Two adjacent judgment steps with no gate between them are one judgment step. - [ ] **Soft status-file probe over repeated probing.** Run the expensive check once in an action that always exits 0 and writes its verdict to a run-scoped file; branch with ordered cheap guards that read that file. One subprocess instead of one per branch — the `task-pipeline.yaml` quality-gate idiom. - [ ] **Order guards cheapest-discriminating-first.** The first passing guard wins, so a `test -f` ahead of a `spur … --json` parse skips the expensive call on the common path. - [ ] **No guard recomputes what a prior node already wrote to disk.** - [ ] **`iterationBound` from the budget, not from optimism.** Set it to the observed maximum plus one; a bound of 10 on a 40-second gate is a seven-minute worst case nobody chose. - [ ] **Fan out only genuinely independent branches** (`type: parallel`, transition-flow). Serial nodes with no data dependency are pure dead latency. - [ ] **`--async` when the caller does not need the terminal state inline**, then follow with `spur workflow trace --follow`. ### Observability is an authoring decision, not a run flag The flags (`--detail`, `--verbose`, `--trace-file`, `--follow`, `--output`) are catalogued in [../workflows.md](../workflows.md); they only expose what the definition already made legible. - [ ] **Name states/nodes after the outcome they establish, not the tool they invoke.** `quality-gate-passed` reads at 3am; `run-script-2` does not. - [ ] **`description` carries the WHY** of the workflow; a one-line comment carries the why of any non-obvious guard order or `iterationBound`. - [ ] **Every gate writes a machine-readable verdict to a run-scoped file.** It is the guard's input *and* the post-mortem's evidence — one artifact, two consumers. - [ ] **Declare `failureStates`** so a failed run reports `status: 'failed'` instead of finalizing as a `done` run that landed somewhere bad (the 0425 reader contract). - [ ] **`env.allow` lists exactly what is used** — no more; an over-broad allowlist is an undocumented dependency. - [ ] **While tuning:** `--detail full` plus `--trace-file`, and compare traces. **In production:** default detail, retained run log. --- ## 3. Node simplicity budget Simplicity is the operating constraint, and it is already measurable — `spur workflow validate` reports it with a `warn`/`error` level. Do not invent a second threshold; author to the ADR-115 tiers frozen in [surface governance §1.2](../../../../../../docs/design/harness-surface-governance.md). | Element | Clean | Warn (advisory) | Error | | --- | --- | --- | --- | | `shell` action `command` | ≤5 logical commands (split on newline, `;`, `&&`, `||`; blank/`#`/structure tokens skipped) | **6–10** | **>10** commands or **>800** characters | | Shell transition guard | ≤3 logical commands — one predicate over a result file | **4–5** | **>5** | | `agent.run` `input` | A slash command or skill invocation (ADR-043), ≤1000 chars | non-slash prompt (severity by raw length: <200 low, ≤1000 medium) | **>1000** chars, slash-led or not | | `agent.run` output check | `expectFile` or `requireDiff` declared | neither declared | — | | Node count | Every node earns its transition round-trip | A node that always runs immediately after another, with no guard between them, is one node | — | **When a program breaches a cap, do not reformat to dodge the measure.** Joining lines with `&&` moves the complexity, not the ownership. Move the program to one of the five recorded owners from `docs/design/workflow-shell-ownership.md`: (a) public `spur` verb (consent-gated), (b) application service, (c) least-privilege built-in action kind, (d) workflow-relative external extension, or (e) a deliberately-stays-shell exception. (e) is valid only inside the warn band — above an error cap the program moves to (a)–(d). **Every remaining warn-band shell program carries a one-line `#` reason**: a YAML comment directly above the action or guard, e.g. `# (e) ` or `# (d)