A Runbook Authoring Prompt That Writes the Whole Runbook

The honest truth about runbooks: most teams know they need them, write three, and let the rest rot as TODO links in a wiki. Writing a good one from scratch takes an afternoon nobody has during a quiet week and that nobody can spare during a loud one. A runbook authoring prompt breaks that loop by turning a service description into a complete draft you edit instead of author.

The keyword here is complete. A prompt that returns "here are some steps you might take" wastes your time. The one worth reusing returns four locked sections: a failure-mode catalog, a diagnostic guide per failure, recovery and rollback procedures with actual commands, and an escalation matrix. Same shape for every service.

This post shows how to build it, why the vendor guides won't help, and where the model needs a human before the runbook goes live.

What a runbook authoring prompt produces

A runbook authoring prompt is a reusable AI prompt that converts a service description plus its dependencies and recent incidents into a structured operational runbook. The output contract is fixed: failure modes, diagnostics, recovery, escalation. The reliability of the format is the product.

Search "runbook automation" and you'll find vendor tooling, not authoring help. The incident.io runbook automation guide is a thorough comparison of platforms that execute runbooks, and it assumes the hard part, writing the thing, happens somewhere else. The one popular AI runbook gist on GitHub is a single prompt with no variables and no locked output, so two engineers get two different shapes. Neither solves the repetition problem.

What you can do with this prompt

• Generate a first-draft runbook for a service that has none, in minutes instead of an afternoon.
• Backfill runbooks across a whole service catalog with one consistent structure.
• Turn the patterns from your last ten incidents into named failure modes with diagnostics.
• Produce an escalation matrix that maps severity to who gets paged and when.
• Refresh a stale runbook by re-running with the latest dependency list and incident history.

Anatomy of the prompt pack

Variables
  {{service_description}} – what it does, runtime, key dependencies
  {{dependencies}}        – upstream/downstream services, data stores
  {{recent_incidents}}    – last 5-10 incidents: symptom + cause + fix
  {{severity_levels}}     – your sev definitions (sev1..sev4)
  {{escalation_contacts}} – teams/roles, NOT individuals' phone numbers

Prompt
  Role: SRE writing a runbook on-call will use under pressure.
  Task: build a runbook from the service description and incident history.
  Output contract (locked):
    1. Failure-mode catalog – named modes, likely symptoms
    2. Diagnostic guide      – per mode: what to check, in what order
    3. Recovery & rollback   – exact steps, marked [VERIFY] where guessed
    4. Escalation matrix     – severity -> who to page -> when
    5. Gaps                  – what the author must fill before publishing

The recent_incidents variable is what turns a generic runbook into yours. Anthropic and others have noted the pattern that works: audit the last 50 incidents, find the top 10 repeating modes, and define diagnostics for each rather than handing an agent open-ended authority. The prompt does the same with whatever incident history you paste in.

How models behave when authoring runbooks

The differences are concrete enough to plan around.

Claude is the steadiest at holding the four-section contract through a long service description and keeps diagnostics ordered by likelihood rather than dumping a flat checklist. GPT-4o writes crisper recovery steps but tends to omit the escalation matrix unless it's the last instruction in the prompt; restate it on the final line. Gemini produces good failure-mode catalogs from sparse input but is the most likely to invent a command, so the [VERIFY] discipline matters most there.

No model knows your rollback command. That's not promptable. It's why the gaps section exists.

Prompt-craft patterns

Pattern 1 — incident-grounded failure modes. Derive the catalog from real history, not from imagination.

Build the failure-mode catalog primarily from {{recent_incidents}}.
Only add modes not seen in history if they're obvious for this
service type, and label those "INFERRED".

Pattern 2 — diagnostics as ordered checks. A runbook used under stress needs an order, not a menu.

For each failure mode, list diagnostic checks in the order an
engineer should run them, fastest-to-rule-out first. Number them.

Pattern 3 — the escalation refusal. Don't let the model invent who to page.

Use only the roles in {{escalation_contacts}}. Never invent a
person, team, or contact method. If a severity has no mapped
contact, write "ESCALATION GAP" and list it under Gaps.

Here's the opinionated part: an escalation matrix is the section everyone skips and the one that matters most at 3 a.m. A runbook that nails diagnostics but leaves "who gets paged" blank fails exactly when it's needed. Force the matrix, and force the model to flag the gap rather than fill it with a guess.

Variables you'll set

Getting started

1. List the service's dependencies and pull the last ten incidents.
2. Fill {{recent_incidents}} with a one-line symptom, cause, and fix for each.
3. Run the prompt on Claude for contract fidelity.
4. Search the output for [VERIFY] and confirm every tagged command.
5. Resolve every line under "Gaps" and "ESCALATION GAP" before publishing.
6. Re-run quarterly with fresh incidents so the runbook doesn't rot.

A runbook is the thing your on-call shift reaches for. The handoff that hands it over matters just as much, which is why this pairs with the on-call handoff brief prompt for turning 48 hours of alert noise into a clean shift summary. And when a runbook step fails to prevent an outage, the blameless incident postmortem prompt feeds new failure modes right back into your next runbook draft.

In the catalog, the Agent Operations Runbook Generator covers this exact job, and the Incident Postmortem Agent Pack turns the incidents that feed your {{recent_incidents}} variable into structured timelines.

Write the runbook the way you'd want it at 3 a.m.: named failure modes, ordered diagnostics, verified commands, and a clear page. The prompt gets you 80% there. The [VERIFY] pass and the gaps section get you the rest.