skills

skills/wf-workflow/references/troubleshooting.md

@@ -0,0 +1,48 @@
+# Workflow Troubleshooting Reference
+
+Use this when a source, capability, artifact, deployment, or run is missing,
+unrunnable, or surprising.
+
+## Missing Capability
+
+Check in this order:
+
+1. `wf.admin.list_sources`
+2. `wf.admin.inspect_source`
+3. `wf.workflow.list_capabilities`
+4. `wf.workflow.inspect_capability`
+
+Remember: MCP control tools are not workflow capabilities. They appear in
+MCP `tools/list`, not `wf.workflow.list_capabilities`.
+
+## Unrunnable Deployment
+
+Run `validate_deployment` before `run_deployment`.
+
+Common diagnostics:
+
+- `binding_missing`: deployment lacks a logical-to-concrete source binding.
+- `source_missing`: bound concrete source does not exist or is disabled.
+- `capability_missing`: required node/reducer is not available.
+- `schema_changed`: saved snapshot no longer matches current source.
+- `source_unreachable`: live check could not contact an upstream source.
+
+Use `live_check=true` only when you intentionally want to contact upstream
+sources. It may spawn stdio servers or perform network I/O.
+
+## Run Debugging
+
+If a run fails:
+
+1. Read `status`, `error`, `diagnostics`, and `trace_count`.
+2. Use `inspect_run` for stored summary.
+3. Use `read_run_trace` with a bounded range.
+
+Do not request full traces unless the user explicitly asks and the trace is
+known to be small.
+
+## Harness Problems
+
+Some LLM harnesses do not refresh `tools/list` mid-session. Do not rely on new
+saved workflows becoming new tools. Use `run_deployment` and `call_capability`
+instead.