How to write an on-call runbook that actually gets used

Almost every team has runbooks. Almost none of them get used at 3 a.m. They're too long, out of date, or buried three wiki-links deep — so the on-call engineer just starts poking at dashboards instead.

A runbook earns its keep only if a tired human can follow it under pressure. Here's how to write one that clears that bar — and why a good runbook is also the safest path to automating the incident away entirely.

Why runbooks rot

• Written for the author, not the responder. Full of context the on-call person doesn't have.
• Too long. A wall of prose isn't a runbook; it's an essay.
• Never verified. If nobody's run it since it was written, assume a step is wrong.
• Hard to find. If it isn't linked from the alert, it doesn't exist.

The anatomy of a runbook that works

Keep the fix copy-pasteable

The body of a good runbook is numbered, executable steps — not paragraphs. The 3 a.m. brain wants kubectl rollout restart deploy/payments, not "consider restarting the affected deployment."

Always include "verify" and "rollback"

The two steps people skip are the two that matter most under stress: how do I know it worked, and what do I do if it didn't. A runbook without these makes an incident worse by giving false confidence.

Link it from the alert

The single highest-leverage change: attach the runbook link to the alert itself, so it's one click from the page — not a wiki search.

Keep them alive

• Review after every use. If a step was wrong or missing, fix it before you close the incident — that's the moment you know the truth.
• Delete dead ones. A wrong runbook is worse than none.
• Own them per service. The team that owns the service owns its runbooks.

From runbook to auto-remediation

Here's the payoff: once a runbook is precise, verifiable, and proven, it's ready to be automated. If the same incident recurs with a known fix, why wake a human at all?

That's exactly how PagerCo's Autopilot works — a runbook's steps become an action it can run autonomously, but only under guardrails: it matches a specific incident type, executes the fix, verifies the incident actually cleared, and escalates to a human if it didn't. You choose how far to trust it — suggest a fix, require approval, or let it run automatically for the well-understood cases. A good runbook is the blueprint; Autopilot is the hands.

Want to turn your best runbooks into auto-remediation? Start a free trial →, or read how AI investigation cuts MTTR.

Written by the team building PagerCo.