runbook_authoring v1.0.0

name: "runbook_authoring" description: "Write operational runbooks that a tired on-call engineer can actually follow: checkable steps, decision branches, prerequisites, and rollback points. Use when a team needs a runbook written or an existing one rewritten, like 'write the runbook for this deploy' or 'make our on-call playbook usable'." metadata: { "includeInPrompt": true }

Runbook Authoring

Purpose

Most runbooks are written to be read, not followed. They read like essays, and at 3am nobody reads essays. A good runbook is a checklist: one procedure, steps in order, each step an action plus its expected result, decision branches for the common forks, and the rollback placed before the point of no return. This skill covers the writing craft of runbooks, not the process of running an incident.

Workflow

1. Scope: one procedure, one doc

Name the trigger up front (the exact alert name, symptom, or deploy event that means "open this runbook") and name the done state (what "fixed" or "shipped" looks like, in observable terms). If the doc covers two procedures, split it. If you cannot state the done state in one sentence, you are not ready to write the steps.

2. Prerequisites and blast radius go at the top

Before any steps, list: the access or credentials needed, the systems that will be touched, what can break if a step goes wrong, and how to abort cleanly. This block is short, a few bullets. It exists so the engineer knows whether they are qualified to run this at all before they start.

3. Write checkable steps

Each step is two parts: the action and the expected result. An action without an expected result is a guess; the reader has no way to know they did it right. Never substitute a paragraph of prose for a step. Format every step as:

Step N. <action in plain imperative>
        Expect: <what you should see>

Prefer exact commands over descriptions of what to do. A command like kubectl rollout status deployment/api -n prod beats "check the rollout status". If the reader has to translate your words into a command, you made them do your job.

4. Decision branches, kept shallow

Write branches as "If X, do Y", with the check and the action on the same line or two. Keep nesting to one level. Rare branches do not belong inline; link out to a separate doc and keep the main path clean. A runbook with four nested branches is a flowchart, and nobody follows flowcharts at 3am.

5. Place rollback before the point of no return

Identify the step after which the procedure cannot be undone cleanly. The rollback step sits immediately before that step, not in an appendix at the end. The reader should see the exit while it is still available, not after they have passed it.

6. Freshness rule

Every runbook names an owner and carries a last-verified date. "Verified" means someone walked the steps against the live system and every expected result matched. A runbook that has not been verified in six months is a rumor; flag it. Retire runbooks for procedures that no longer exist instead of letting them rot.

Skeleton template

Copy this into the finished runbook and fill every block:

# Runbook: <procedure name>

Trigger: <alert name, symptom, or event that opens this doc>
Done state: <one sentence, observable: what "finished" looks like>

## Prerequisites
- Access needed: <credentials, roles, VPN>
- Systems touched: <list>
- What can break: <worst-case per step cluster>
- How to abort: <clean exit before the point of no return>

## Steps

Step 1. <action in plain imperative>
        Expect: <what you should see>
        If <condition>: <do this instead>  (branch only if common)

Step 2. <action>
        Expect: <what you should see>

...

ROLLBACK (before the point of no return at Step <N>)
- <exact reversal commands>

## Point of no return
Step <N>: after this, rollback is not possible; proceed only if all
previous expectations matched.

## Freshness
- Owner: <name or handle>
- Last verified: <YYYY-MM-DD>
- Verified means: <what was checked, e.g. "walked steps 1-8 against staging">
- Retire when: <condition, e.g. "service is decommissioned or deploy is fully automated">

Output Contract

A finished runbook contains the skeleton above, fully filled in, with no empty blocks. Every step has an action and an expected result. Branches are one level deep, with rare cases linked out. Rollback sits before the point of no return. The owner and last-verified date are real, not placeholders.

Readability test: hand the doc to someone who did not write it and ask them to walk the steps against a test environment without asking questions. If they stall, guess, or interpret, the runbook fails and goes back to drafting. This test is the deliverable's bar, not a suggestion.

Operating Rules

• Steps are commands plus expected output, not explanations. Explain in a linked appendix if needed, never inline.
• One procedure per doc. Two procedures means two docs.
• Name the trigger and the done state before writing step one.
• Put rollback before the point of no return, never at the end.
• Every runbook names an owner and a last-verified date. Undated runbooks are unverified by definition.
• Verify by walking the steps, not by rereading them. Reading checks the prose; only execution checks the steps.
• Retire runbooks for procedures that no longer exist. A dead runbook that looks alive is worse than none, because it gets followed.
• Keep branches shallow and rare cases linked out. The main path is the 3am path.
• Rewrite, do not patch, when the procedure changes shape. A rewritten runbook re-verifies; a patched one usually does not.