Workflow Operational Runbook
Definition. The documented procedure for operating a workflow, covering routine checks, common failures and their resolution, escalation and the location of logs and dashboards. The runbook is what allows someone other than the builder to operate the workflow.
How it works. Document the routine checks and their expected results. List the common failure modes with the diagnostic step and the resolution for each. Include the escalation path and the owner. Keep it next to the workflow definition rather than in a separate wiki, since proximity determines whether it is updated. Review after every incident.
Example. A workflow fails at 2 a.m. and the on-call engineer has never seen it. The runbook lists the three most common failures, and the symptom matches the second: an expired credential. The resolution is a documented rotation procedure, and the incident is resolved in 12 minutes. Without the runbook, the engineer would have paged the owner and waited.
Use case. A runbook is required for any workflow in production, and it is the artefact that makes on-call sustainable. It is also a prerequisite for handing over ownership.
Warnings. A runbook stored far from the workflow will not be updated. Never document only the happy path. And never assume the builder will be available, since they will not always be.
Limitations. Runbooks go stale as workflows change, and they cannot cover novel failures. They also require discipline to update after each incident, which is easy to skip under pressure.