# Runbook

A runbook documents a repeatable operational procedure with prerequisites, ordered actions, verification, and escalation guidance.

- Type: artifact
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-10-19
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/runbook/>)

## What it means

A runbook describes how to perform a known operational task and recognize its successful completion. It may be a human-readable checklist, executable automation, or both. An investigative playbook helps diagnose an uncertain problem; a runbook normally starts with a better-understood task and outcome.

## Why it matters

Clear procedures reduce dependence on one person’s memory and help responders work consistently under pressure. Explicit checks also expose hidden permissions and dependencies before an urgent task fails halfway through.

## When to use it

Use runbooks for recurring maintenance, known recovery actions, and release procedures. Keep them proportionate to task risk. When the situation is novel or prerequisites do not hold, stop and investigate instead of applying a familiar procedure blindly.

## How it works

1. State the task, owner, prerequisites, permissions, and expected outcome.
2. Write ordered actions with observable checks and safe stopping points.
3. Document failure handling, rollback limits, and escalation contacts.
4. Have another operator rehearse the procedure in a suitable environment.
5. Version and review it with system changes; automate stable steps where beneficial.

## A practical example

A support engineer follows a runbook to replay a failed export job. It first checks that no completed export exists, then identifies the exact job, runs the replay, and verifies delivery. Unexpected duplicate state triggers escalation instead of another retry.

## Where it breaks

Outdated procedures can increase rather than reduce risk. Automation can repeat a mistaken assumption faster, and access to a runbook does not ensure the necessary permissions. A document cannot replace judgment about whether its starting conditions apply.

## Common mistakes

- Publishing commands without prerequisites or expected results.
- Storing credentials inside the procedure.
- Changing the system while leaving its recovery instructions untested.

## Sources

1. [OPS07-BP03 Use runbooks to perform procedures](<https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/ops_ready_to_support_use_runbooks.html>) — Amazon Web Services · Official documentation
2. [Architecture strategies for enabling automation](<https://learn.microsoft.com/en-us/azure/well-architected/operational-excellence/enable-automation>) — Microsoft · Official documentation

## Related topics

- [Incident Management](<https://wiki.soroush.uk/topic/incident-management/>)
- [Toil](<https://wiki.soroush.uk/topic/toil/>)
- [Disaster Recovery](<https://wiki.soroush.uk/topic/disaster-recovery/>)
