runbook

Runbook creates or updates an operational runbook for a recurring task or procedure. It is used to document a task that on-call or operations needs to run repeatably, to turn tribal knowledge into exact step-by-step commands, to add troubleshooting and rollback steps to an existing procedure, or to write escalation paths for when things go wrong. It takes the process or task name as an argument and produces a structured Markdown document.

The output follows a consistent template. A header records the owner, frequency (daily, weekly, monthly, or as needed), last updated date, and last run date. The body includes a purpose statement, a prerequisites checklist for access, tools, and inputs, and a numbered procedure where each step carries an exact command or action, an expected result, and an "if it fails" branch. Additional sections cover verification of successful completion, a troubleshooting table mapping symptom to likely cause to fix, a rollback procedure for undoing the change, an escalation table mapping situations to contacts and methods, and a history log of runs.

The skill adapts when connectors are available. With a knowledge base connected it searches for existing runbooks to update rather than starting from scratch and can publish the finished runbook to an ops wiki. With an ITSM system connected it links the runbook to related incident types and change requests and auto-populates escalation contacts from on-call schedules. Authoring guidance stresses being painfully specific, contrasting a vague instruction like "Run the script" with a precise one that names the exact command, flags, and the server it runs on; including failure modes at each step; and testing the runbook by having someone unfamiliar with the process follow it and fixing wherever they get stuck. A note points to a connectors reference for unfamiliar placeholders or to check which tools are connected.