#188 swamp workflow validate: actionable error messages and template scaffolds

Problem

When agents (and humans) write fix workflows from scratch, getting the YAML schema and CEL expressions right takes 1-N validate-fix-rerun cycles. On a recent multi-run agent benchmark (k8s-debug-v2, 5 swamp-variant runs cold-start), this loop was the single biggest variance driver:

The outlier alone burned ~20 turns over the median on validate-fix churn. Not on subtle CEL evaluation errors — on basic things like swamp workflow validate <not-yet-created-name> or swamp workflow validate path/to/workflow.yaml, where the existing error "Workflow not found: <name>" told the agent nothing about how to recover.

Phase 1 — actionable validate errors (already shipped on

feat/suggest-input-flag, commit 598afd9)

Three classes of validate-time errors made actionable:

1. Workflow-not-found: detects file-path inputs (.yaml/.yml//) and explains validate takes a name, points at swamp workflow create. For typos, suggests the closest match and lists existing workflows. For empty repos, prints the literal command to create the workflow.
2. Method-not-found during input validation: lists available methods on the model type (closes the loop with swamp model type describe --methods).
3. Missing required inputs: includes per-arg types and points at swamp model type describe X --method Y.

Live behaviour after compile:

$ swamp workflow validate fix-namespace
error: Workflow 'fix-namespace' not found. No workflows exist in this
repo. Create one with `swamp workflow create fix-namespace`, then edit
the scaffold it produces.

$ swamp workflow validate workflows/fix.yaml
error: 'workflows/fix.yaml' looks like a file path. `swamp workflow
validate` takes a workflow name or ID, not a file. ...

$ swamp workflow validate deploy-aplp
error: Workflow 'deploy-aplp' not found. Did you mean 'deploy-app'?
Existing workflows: deploy-app. Run \`swamp workflow search\` for the
full list.

This phase is implemented and tested (5 new unit tests). Filing the issue to close the loop and capture the design for future reference.

Phase 2 — template scaffolds (proposed, not yet started)

swamp workflow create <name> today emits the same generic stub regardless of intent. Agents and humans then write the entire body from scratch, hitting schema-shape errors that better defaults would have avoided.

Proposal:

swamp workflow create my-fix --from-template <kind>

with starter templates for the common patterns:

• model-method — single model_method step with placeholders for modelIdOrName, methodName, and inputs.
• foreach-list — forEach over the result of data.findBySpec(...), one model_method step per item.
• model-method-with-data-input — model_method step that reads from a prior step's data via CEL.
• parallel-then-summarize — two parallel jobs feeding a third that depends on both.

Each scaffold should:

• Be schema-valid out of the box (so first validate always passes).
• Use placeholder model/method names that fail loudly at run time (not silently at validate time) — __REPLACE_ME__ or similar.
• Include inline comments explaining the CEL syntax used.

The cheapest stop-gap (which we should do regardless): enrich swamp workflow create --help with a richer EXAMPLES block showing the canonical patterns. That alone closes some of the gap because agents do read --help when stuck.

Why this matters

Bench numbers (combined effect of phase 1 + better learning loop):

• Median run: 1-3 validate cycles → expected ~1 cycle.
• Outlier runs (8 cycles): expected to compress to 2-3 cycles.
• Translates to roughly 20 turns saved on tail runs.

Filed as part of an effort tracked at swamp-benchmark (github.com/systeminit/swamp-benchmark) where the same 5-run bench is being used as the regression measurement.