How to Prompt AI to Write a Runbook

A runbook is a document that tells someone how to handle a specific failure at three in the morning when they are not thinking clearly. To prompt AI to write a runbook that actually works, you have to give the model the one thing it cannot infer: what breaks in your system and how you find out. Ask for "a runbook for our payment service" and you get a plausible template. Give it your alert text, your architecture, and your last three incidents, and you get something worth paging someone with.

The difference is entirely in what you put in.

Why the obvious prompt fails

The model has read thousands of runbooks. It knows the shape: symptom, triage, diagnosis, mitigation, escalation, verification. It will produce that shape confidently for any system you name.

The shape is not the hard part, and Google's SRE book makes the same point in its chapter on being on-call: the value of a playbook is in the specifics it carries, not its structure. What the model does not know is that your queue worker silently drops jobs when Redis fails over, that your monitoring dashboard lags by four minutes so the graph always looks fine at the moment of the page, or that the restart script needs a flag nobody documented. Those are the facts a runbook exists to carry. Without them you have a table of contents.

So the prompting problem is not phrasing. It is extraction, which is the recurring theme in most of prompt engineering once you get past the basics. You need to get what you know out of your head and into the context window, and most of it is knowledge you have never written down.

Step one: extract before you generate

Do not start by asking for the runbook. Start by asking the model to interview you.

I need to write a runbook for [service] handling [specific failure].
Do not write the runbook yet.

First, ask me the questions you would need answered to write one that
a colleague could follow at 3am without calling me. Ask them one batch
at a time, hardest first. Stop when you have enough.

This inverts the usual failure. Instead of the model filling gaps with invention, it names the gaps and makes you fill them. The questions it asks are typically better than the ones you would have thought to answer: how do you know this is happening rather than something that looks like it, what does the failure look like when it is only partial, what is the safe thing to do if you are wrong about the cause.

Answer honestly, including "I don't know". A runbook that says "nobody has confirmed whether this is safe to run twice" is more useful than one that quietly assumes it is.

Step two: give it the raw material

Paste in, verbatim:

• **The alert.** The exact text of the page or notification that starts this, including the metric name and threshold.

• **The last two or three incidents of this type.** Chat logs, incident reviews, whatever you have. Messy is fine and messy is better, because the mess contains what actually happened.

• **The commands.** The real ones, with real flag names. If you paraphrase, the runbook gets paraphrased commands and someone will type them.

• **The blast radius.** What else breaks if this stays broken for an hour.

• **Who can approve the dangerous options.** By role, not name.

Redact credentials, customer data, and internal hostnames before pasting any of it. The general discipline for that is covered in prompting AI without leaking sensitive data, and it applies with force here because incident logs are unusually rich in exactly the things you should not be pasting.

Step three: the generation prompt

Write a runbook using only the information I have given you.

Structure:
1. Symptom: what the person sees that made them open this
2. Verify: how to confirm it is this problem and not something similar
3. Immediate mitigation: what reduces customer impact right now,
   before anyone understands the cause
4. Diagnosis: how to find which of the known causes it is
5. Fix, per cause
6. Verify the fix
7. Escalate: who, when, and what to tell them

Rules:
- Every command in a code block, copy-pasteable, no placeholders
  except where I must substitute a real value, and mark those clearly
- Every step that is irreversible or customer-visible gets a warning
  line directly above it
- Where I did not give you the information, write
  "UNKNOWN: [what is missing]" rather than filling it in
- Write for someone competent who has never touched this service
- No preamble, no summary, no encouragement

The UNKNOWN rule is the important one. It converts the model's tendency to invent into a to-do list. Every UNKNOWN in the draft is a question for a colleague, and the runbook is finished when they are all gone.

Mitigation before diagnosis is deliberate, and it is where most self-written runbooks are wrong. At 3am the priority is to stop the bleeding, not to understand the wound. Putting diagnosis first sends a tired person down a debugging path while customers are still failing.

Step four: test it against a tired reader

Take the draft and run one more pass:

You are an on-call engineer who has never worked on this service.
It is 3am. You have been awake for four minutes.

Walk through this runbook literally, step by step. At every step where
you would have to guess, ask a question, or make a judgement call that
is not spelled out, stop and say so.

This finds a specific class of defect: steps that read fine to the author because the author already knows the answer. "Check the queue depth" is meaningless if the runbook does not say where to look. "Restart the worker" is dangerous if it does not say whether in-flight jobs are lost.

Expect the first draft to fail this test in five or six places. That is the test working.

What to keep out of it

Runbooks rot, and the fastest-rotting content is anything that duplicates a system of record. Keep out:

• Architecture explanation. Link to it.

• Anything that changes with a deploy, such as instance counts or specific version numbers.

• Rationale. A runbook is for doing, not for understanding. Put the reasoning in the incident review.

• Every possible cause. Cover the ones that have actually happened, plus the one catastrophic case that has not. A runbook covering fourteen scenarios will not be read.

Keeping it current

The prompt that maintains a runbook is different from the one that writes it, and it runs after every incident:

Here is our runbook, and here is what actually happened last night.

Identify: steps that were wrong, steps that were missing, steps we
skipped because they were not useful. Propose the minimum edit.
Do not restructure the document.

"Do not restructure" is load-bearing. Without it the model rewrites the whole thing every time, and a runbook that changes shape monthly is one nobody trusts.

This pairs naturally with getting an AI coding agent to write a rollback plan, which is the same discipline applied to deploys rather than incidents, and with your broader AI incident response plan if you have one.

If you are writing several runbooks, the style consistency problem is real, and the technique in following a style guide without repasting examples will save you retyping the format rules every time.

FAQ

Can AI write a runbook from just my codebase?

It can write the parts that are visible in code, such as which services call which. It cannot write the parts that only exist in operational memory, which is most of a runbook: what the alert actually means, what has broken before, and which fix is safe to try twice.

How long should a runbook be?

Short enough that a stressed person reads it rather than skimming. One page per failure mode is a good target. If yours is longer, it is probably covering several failures and should be several runbooks.

Should the runbook include the commands or link to a script?

Include them. A link is one more thing that can be unreachable at 3am, and seeing the command before running it is part of how the reader confirms they are in the right place.

How do I stop the model inventing steps?

The UNKNOWN instruction is the practical answer: tell it explicitly to mark gaps rather than fill them. Models default to producing a complete-looking document, and you have to override that default in the prompt rather than hoping.