How Loom works in practice
This guide is for people already past the landing page and quickstart. It explains the operator loop behind Loom so you know which command to run, which artifact to inspect, and where to go next when a run fails.
Command to artifact map
| Command | What it gives you | Next file or page to inspect |
|---|---|---|
loom check | Schema validation result plus a receipt | Fix schema issues, or continue to loom compile |
loom compile --workflow .loom/workflow.yml | Resolved Graph IR | Confirm the plan before you execute |
loom run --local --workflow .loom/workflow.yml | Runtime receipt plus logs directory | Open the receipt, then the pipeline manifest |
| Failing run triage | Pointer-driven diagnosis path | Diagnostics ladder |
The four-step loop
| Step | What you do | What Loom does |
|---|---|---|
| 1. Author | Write .loom/workflow.yml | — |
| 2. Validate | Run loom check | Validates against schema v1, resolves includes, emits a receipt |
| 3. Run | Run loom run --local --workflow .loom/workflow.yml | Executes jobs (host or Docker), writes receipts + manifests + event streams |
| 4. Diagnose | Follow receipt → manifests → events | Pointers lead to the exact failing unit |
Common failure branches
Use these as your first branch instead of reading everything top to bottom.
Schema or authoring failure
Symptom: loom check fails before execution starts.
What to inspect next: the validator error output and Syntax v1.
Runtime failure in a user step
Symptom: loom run --local starts, but a pipeline or job ends in failure.
What to inspect next: Diagnostics ladder, starting from the receipt or pipeline manifest.
Provider or environment failure
Symptom: missing tools, Docker startup issues, permissions problems, or host/container drift.
What to inspect next: Providers overview, Common failures, then the matching system section events.
What the workflow loop produces
| Artifact | Location | Why it matters |
|---|---|---|
| Receipt | .loom/.runtime/receipts/loom-run-local-*.json | Entry point for diagnosis and the run handle you can share |
| Pipeline summary | .loom/.runtime/logs/<run_id>/pipeline/summary.json | Confirms overall run status and exit code |
| Pipeline manifest | .loom/.runtime/logs/<run_id>/pipeline/manifest.json | Points to the failing job |
| Job manifest | .loom/.runtime/logs/<run_id>/jobs/<job_id>/manifest.json | Points to the failing step or system section |
| User step events | .loom/.runtime/logs/<run_id>/jobs/<job_id>/user/execution/script/<NN>/events.jsonl | Shows the exact failing unit |
| System section events | .loom/.runtime/logs/<run_id>/jobs/<job_id>/system/<section>/events.jsonl | Explains provider, cache, or artifact failures |
Reference: Receipts contract · Runtime logs contract · loom run
The diagnosis path in practice
- Open the receipt or logs directory for the run.
- Read
pipeline/manifest.jsonto identify the failing job. - Open
jobs/<job_id>/manifest.jsonto find the failing step or system section. - Read the pointed
events.jsonlfile for the exact error evidence.
If you need the full scan pattern with examples, switch to the Diagnostics ladder.
Next steps
| Goal | Link |
|---|---|
| Run your first workflow end to end | Hello Loom |
| Practice pointer-chain diagnosis | Diagnostics ladder |
| Learn the full workflow syntax | Syntax v1 |
| Explore the CLI surface | CLI overview |