How to Write a Deployment Runbook With AI
"Bump the tag and restart — ask Priya if it breaks" is not a runbook, and Priya is on a plane. Here's how to turn what you actually do into a deployment runbook someone else can execute: preconditions, ordered steps, a verification at every gate, a failure path that isn't hope.
Build a Runbook PromptThe deploy lives in one person's head, and they're on a plane
Ask how the service gets deployed and you'll get a shrug and a sentence: "bump the image tag and restart it, Priya usually does it." There might be a wiki page, last edited fourteen months ago, describing a step that no longer exists. It works, in the sense that it has always worked, because the person doing it carries the parts that were never written down — that you don't ship during the Monday reindex, that the health check lies for the first thirty seconds, that if the replicas hang you pin the old tag rather than wait. None of that is knowledge the team has. It's knowledge Priya has. The day someone else has to ship, they aren't executing a procedure; they're improvising in production.
So you ask an AI for a deployment runbook, and what comes back looks *exactly* like the thing you wanted. Numbered steps. Confident commands. A rollback mentioned at the end. It is also fiction: the model has never seen your cluster, so the namespace is invented, the health path is a guess, and "verify the pods are running" isn't a verification at all — a pod can run perfectly while serving five hundreds to every request. Fiction shaped like a procedure is worse than the shrug, because someone will follow it at 2am. NewPrompt's part here is narrow and worth stating flatly: it helps you build the prompt. It has no reach into your source control, CI/CD, cloud provider, servers, or terminal; it runs no commands; it doesn't deploy, roll back, smoke test, monitor, or approve anything. Every command in a useful deployment runbook comes from you — the model can shape and order what you supply and pester you for the gaps, but any command it produces on its own is candidate text you verify against the real environment before anyone runs it.
Why a plausible runbook is more dangerous than none
A missing runbook makes people careful. A wrong one makes them confident, which is the failure mode you actually have to design against. Ask for a deploy procedure without supplying your procedure, and the draft fails in ways that are hard to see precisely because it reads so well:
- The commands are invented. Your namespace, your service name, your deploy mechanism, your dashboard — none of it is knowable from a generic ask, so the model produces a well-formed guess. It looks like a command. It isn't yours.
- "Verify it worked" isn't verification. A step is verified when there's an observable signal with an expected value — six replicas reporting the new build sha, error rate at baseline. "Check the deploy succeeded" just relocates the question.
- Failure gets one line at the bottom. Real deploys fail at a specific step, and what you do depends on which one. A single "if something goes wrong, roll back" tells the person at 2am nothing about whether they're past the point where rolling back is even the right move.
- The preconditions are missing entirely. The freeze window, the access you need before you start, the dependency that must be healthy, the previous tag you have to record — these are the things whose absence you discover halfway through, with traffic on the new version.
- Nobody owns anything. A runbook without a named decision point turns every judgment call into a group chat, at the exact moment nobody wants to be the one to decide.
Step 1: Write down what you actually do, quirks included
Start by narrating a real deploy, not an idealized one. What is being deployed, to which environment, by what mechanism, and who owns it? Then the parts that live in someone's head: the real commands you type, the order you type them in, the thing you check before starting, the wait that's always longer than it should be, the dashboard you have open on the second monitor. If the real sequence includes "then I stare at the graph for five minutes," write that down — that's a verification step nobody ever wrote down as one, and it belongs in the runbook.
Two practical rules for this material. Keep secrets and environment-specific values out of what you paste — the runbook should reference where a credential comes from, never carry its value, and a token in a document is a token in every copy of that document forever. And where a command varies by environment, make it an explicit placeholder rather than a real string, so the executor is forced to make a deliberate substitution instead of running staging's command against production. What you're assembling is the raw material: the model's job is to shape it, not to know it.
Step 2: State what must be true before anything starts
Preconditions are the cheapest section to write and the one that saves the worst afternoons. They're the answer to "what does the executor need to be true before they touch anything": the access and permissions they need in hand, the dependencies that must be healthy, the artifact that must already exist and be verified, the backup taken, the approval given, the freeze window checked. Each one written as something checkable — not "make sure you have access" but "confirm you can run the deploy command against the target environment," which either happens or doesn't.
Keep the scope tight to execution. The question here isn't "should we ship this?" — whether the change is ready, tested, and approved is a decision made before this document opens, and it's a different artifact with a different job. Your preconditions are the narrow, practical set that a person about to run the procedure must verify in the next two minutes. A runbook that re-litigates the release decision at step zero is one nobody reads to step one.
Step 3: Break it into steps that carry their own context
Now order it. One action per step, unambiguous, and — this is the whole test — no step may assume context that isn't written down. The executor is a competent teammate who has never deployed this service and cannot ask you, because you're on a plane. That constraint kills the two habits that make runbooks useless: the implicit step ("obviously you'd drain connections first") and the shorthand that only means something to whoever wrote it.
The Deployment Runbook Prompt is a copy-paste prompt built on exactly that framing — it casts the model as a release engineer writing for a teammate who'll execute it without you present, and its structural rule is that every step which changes production carries a verification and a failure path. The Markdown Output Builder is the tool that builds a prompt in that shape, and its runbook setup already carries the sections: pre-deploy checks, ordered deploy steps, verification, on-failure, post-deploy verification, sign-off. Both hand you prompt text you run in your own AI assistant. The draft that returns is a starting shape — and it's worth being blunt that a runbook is not right because it's well-organized. It's right when the commands in it are the commands your environment actually takes, which only you can confirm.
Step 4: Give every step a real check and a real branch
This is the part that separates a deployment runbook from a list of commands. Every step that changes production gets two things attached. A verification: an observable signal with an expected value, checkable by someone who doesn't know the system — "all six replicas report build sha `<tag>` on `GET /healthz`" rather than "confirm the rollout is fine." And a failure branch: what to do when that verification doesn't come back clean. Not one generic line at the end — a branch at the gate where it fails, because the answer differs by step. Early on, retry. Later, stop and escalate. After the migration, the answer changes entirely.
The rollback hook belongs here, as one branch among several rather than the document's subject. At each gate the on-failure line resolves to something specific: retry this, stop and escalate to whom, or invoke the rollback plan — where the rollback plan is its own document, because the triggers, the reverse of every forward step, and the point of no return are a real piece of work in their own right. The Rollback Plan Prompt is the copy-paste prompt for that one, generated by the Multi-Step Prompt Builder — a tool that emits a sequential prompt workflow, each step with its objective and expected output. Worth keeping straight: that tool sequences *prompts you run in your AI assistant*, not the operational steps of your deploy. Your runbook links out to the rollback plan; it doesn't try to be it.
Name the decision-maker while you're here. Where a step's failure needs a judgment — keep waiting or roll back — the runbook says who makes that call, by role, not by hoping someone volunteers. The document's job is to get the right person deciding with the right information in front of them, not to make the decision for them.
Step 5: Define done, then rehearse it with someone else
A deploy isn't finished when the command exits, so say what finished means. Post-deploy smoke checks come first: a short, ordered set of critical paths confirmed working, each with an unambiguous pass or fail — a real search returns results, a real order goes through. Not a regression suite, just the handful of paths whose breakage would make this deploy a mistake. The Post-Deploy Smoke Test Prompt is a copy-paste prompt for that shape — the critical paths only, ordered highest-risk first. Then exit criteria that leave nothing to interpretation — the version live everywhere, error rate at baseline for a stated window, smoke checks passed — and a sign-off saying who confirms it and who gets told.
Then do the thing that actually validates the document: have someone else read it, ideally someone who has never deployed this service, and walk it in a safe environment. Every gap surfaces in the first three minutes — a command that needs access they don't have, a step assuming a tab they don't have open, a verification they can't interpret. This is where a drafted runbook becomes a real one, and it's not optional. The model produced a document from your description; the dry-run is what proves the description was complete. Until someone else has run it, you have a hypothesis about your deploy, written down neatly.
Common mistakes
The patterns that produce a deployment runbook nobody can safely execute:
- Shipping the model's commands. It has never seen your environment; anything it produces unprompted is a guess in the shape of a command. Supply your real ones or use explicit placeholders.
- Accepting "verify it succeeded" as a verification. A check needs an observable signal and an expected value. "Pods are running" passes while the service returns errors on every request.
- One rollback line at the bottom. Failure is per-step. Put the branch at the gate where it happens, and let it point at the rollback plan rather than trying to inline one.
- Writing for yourself. If a step assumes context you happen to have, the runbook works only when you run it — which is the exact situation it exists to fix.
- Putting real secrets in the document. Reference where a credential comes from; never carry its value. A runbook gets copied, pasted, and shared.
- Never rehearsing it. A runbook nobody else has walked is a draft. Dry-run it with a teammate — NewPrompt doesn't run your deploy or check that the steps work.
A worked example: rolling out a containerized service
One stateless service, a rolling update, and the difference between the sentence the team has now and a step someone else could actually run.
A one-sentence tribal deploy note and the fictional procedure a thin ask returns, versus one real runbook step carrying preconditions, the user's own commands, an observable verification, a failure branch with a rollback hook, a named decision-maker, smoke checks, and exit criteriaTHE RUNBOOK YOU HAVE TODAY:
"Deploy search-api: bump the image tag and restart. Ask Priya if it breaks."
WHAT A THIN ASK RETURNS:
ask: "write a deployment runbook for our containerized service"
-> 1. Update the image tag in the deployment.
2. Verify the pods are running.
3. If it fails, roll back.
every value is invented: the namespace, the service name, the health
path, the dashboard. and step 2 is not a verification — a pod runs
happily while returning 500 to every request.
WHAT YOU SUPPLY (the facts only you have):
service search-api, stateless, 6 replicas behind the LB
mechanism rolling update via <your deploy command>
health GET /healthz -> 200 + the build sha
signal the error-rate panel the team already watches
freeze no deploys during the Monday reindex
rollback <your rollback command>, pins the previous tag
owner whoever is on call for search
ONE STEP, WRITTEN SO SOMEONE ELSE COULD RUN IT:
STEP 3 - roll out the new image
PRECONDITIONS
- image <tag> present in the registry (step 2 confirmed)
- no reindex in progress (step 1 confirmed)
- previous tag recorded in the deploy ticket (the rollback needs it)
ACTION
run: <your deploy command> with the new tag
VERIFICATION
- all 6 replicas return the new build sha on GET /healthz
- error rate stays at baseline for 5 minutes
(NOT "the pods are running")
ON FAILURE
- replicas stuck > 5 min, OR error rate above baseline
-> stop. do not proceed to step 4.
-> run: <your rollback command>, previous tag from the ticket
-> that is the hook; the rollback plan itself (triggers,
reverse steps, point of no return) is its own document
DECISION
on-call for search decides continue vs roll back.
the runbook informs that call; it does not make it.
POST-DEPLOY SMOKE CHECKS
- a real search query returns results pass / fail
- the search page renders for a logged-in user pass / fail
EXIT CRITERIA
- 6/6 replicas on the new sha
- error rate at baseline for 15 min
- both smoke checks pass
- on-call signs off in the deploy channel; team notified
STILL YOUR JOB:
every command above is yours or a placeholder — none invented by the
model. it shaped and ordered what you gave it. you confirmed each
command against the real environment, and you had someone who has
never deployed search-api walk the whole thing before it mattered.Where this fits in NewPrompt
This document sits in the stretch between "tests pass" and "safe in production," which is what the AI Deployment & Release Workflow covers end to end: put the model in a release engineer's seat, run a readiness review, plan the deploy and its rollback, then decide what you'll watch and how you'll know the launch is healthy. This guide is the execution procedure inside that arc. The workflow supplies the prompts and the step order; you run them in your own AI tool, and as its own copy puts it, running the actual deploy and owning the go/no-go stays with you. The pieces this guide leans on are specific: the Deployment Runbook Prompt is the copy-paste prompt for the procedure, the Markdown Output Builder builds a prompt in that six-section shape, and the Post-Deploy Smoke Test Prompt covers the critical-path checks at the end.
The neighbours matter, because deployment is a crowded word. A rollback plan answers "how do we undo this, and when do we decide to?" — it's the branch your runbook hooks into, not the runbook itself. Release readiness answers "should we ship at all?", which is settled before this document opens. A rollout strategy — canary percentages, cohorts, bake time — is about exposure over time, while this is about executing one deployment to one environment. Monitoring design decides which alerts should exist; your verification steps just read the signals that already do. And the runbook is deliberately mechanism-agnostic: whether you deploy blue-green, rolling, or behind a flag, it documents the steps of the mechanism you have rather than arguing for one.
It's also worth saying who this isn't for: if your pipeline genuinely is the procedure, verification included, you don't need this document — you need to keep it that way. What it earns its keep for is the situation at the top, where one person knows how to ship and that knowledge has never left their head.
The test is one person. Someone who has never deployed this service, alone, at an unreasonable hour, knowing at every step whether to continue, stop, or undo. A deployment runbook that survives that is a good one whatever it looks like, and one that doesn't is decoration. The model is genuinely fast at turning your scattered knowledge into that shape — the ordering, the per-step structure, the section you forgot. What it can't supply is the substance: your commands, your signals, your freeze window, your point of no return. Give it those and you get a draft worth reviewing. Give it nothing and you get fiction with numbered steps, which reads the same at 2am and doesn't survive contact with production.