A good runbook lets a competent responder do the right thing without improvising under stress.
Context
Runbooks convert operational knowledge into executable procedures. They are not long theory documents. They are concise operational guides for situations where time, clarity, and safety matter more than perfect prose.
In a lifecycle-aware system, runbooks should encode the same release boundaries the team reviewed earlier. For brownfield systems, that often means explicit rollback, fail-closed behavior, and coexistence-safe fallback steps.
Inputs
- incident-playbook -- produced by the preceding skill in the lifecycle
- monitoring-config -- produced by the preceding skill in the lifecycle
- ci-cd-pipeline -- produced by the preceding skill in the lifecycle
Process
Step 1: Define the Trigger and Owner
Specify:
- what alert or symptom activates the runbook
- who is expected to start it
- what severity range it applies to
- when to escalate instead of continuing solo
Step 2: Capture Preconditions and Safety Boundaries
Before the first action, state:
- what must be true before executing the procedure
- which paths must be preserved
- what should fail closed if the system is unsafe
- whether rollback or fallback is preferred over partial manual repair
- where any referenced threshold, policy, or guard decision comes from
Step 3: Write the Response Steps
Use numbered steps with:
- exact decision points
- commands, dashboards, or checks to use
- expected observations
- branch conditions for rollback, fallback, or escalation
- explicit source or value for any threshold like "communication threshold" or "expected recovery window"
Avoid prose that forces the reader to infer the next move.
Step 4: Add Verification and Communication
A runbook must say:
- how to confirm the mitigation worked
- which metrics or logs prove recovery
- who gets updated and how often
- what evidence should be captured for post-incident follow-up
Step 5: Keep the Runbook Executable
Validate that someone other than the author can follow it. Update the runbook after incidents, failed drills, or major release changes.
Outputs
- operational-runbook -- produced by this skill
- escalation-checklist -- produced by this skill
Quality Gate
- Trigger and intended owner are explicit
- Decision points and branch conditions are explicit
- Rollback or fail-closed path is included where applicable
- Recovery verification and communication steps are included
- Another responder could execute the procedure without improvising major steps
Anti-Patterns
- Narrative instead of procedure -- If every step has to be inferred, it is not a runbook.
- Author-only knowledge -- A runbook that depends on tribal memory is already failing.
- No rollback or safe-stop branch -- Procedures that assume the happy path are dangerous under pressure.
- Outdated environment details -- Old commands and links are silent operational hazards.
- Missing communication checkpoints -- Recovery can still fail if stakeholders do not know the current state.
- Magic thresholds -- Saying "if the threshold is exceeded" without naming the threshold or policy source forces responders to guess.
Related Skills
- monitoring-observability -- provides the signals that trigger runbooks
- incident-response -- defines containment and command structure
- retrospective -- improves runbooks after incidents
Distribution
- Public install surface:
skills/.curated - Canonical authoring source:
skills/07-operations/runbooks/SKILL.md - This package is exported for
npx skills add/updatecompatibility. - Packaging stability:
beta - Capability readiness:
beta