Writing runbooks
REQUIRED BACKGROUND: the
skill (hard rules, truth rules, style).
Overview
A runbook is read by someone in a hurry, often mid-incident. Every rule here serves that reader: order, one action per step, copy-pasteable commands, and danger marked where the eye already is.
Write from a real run: every step one actually taken, every failure named one that actually happened. A procedure imagined at the desk is a draft, not a runbook.
When to invoke, and not
Invoke for anything a person will execute: runbooks, setup and release procedures, troubleshooting entries, operational checklists, and the operator-facing strings inside a system. Do NOT invoke for design rationale (
) or for reference material nobody executes. If the procedure has not been run at least once, either run it first or label the document a draft; publishing an untested procedure as a runbook is the defect, not the labeling.
Structure
- Title carries the scope: "MVP runbook (Reddit)", "Release runbook".
- Open with what this document is relative to its siblings: "this doc is the sequence; deep detail per step lives in X." State what it does NOT cover.
- Legend up front when steps differ in risk, applied to every command: safe to run anytime / operator-only (writes to production) / manual step outside the terminal.
- TL;DR happy path first, then the same steps broken out as numbered sections for when the reader needs only one.
- Version-pinned prerequisites before any command, each with a check command to confirm it.
- Numbered ordinal steps (not bullets), one action each, present tense or imperative, with a visible actor.
- Every command copy-pasteable as-is, with concrete placeholder values ("common paths: , "). Label variants inside the code block:
bash
# safe mode
app sync run --channel=reddit --limit=100
# live mode (writes to the provider)
app sync run --live --approval-token=...
- Ordered steps state the consequence of wrong ordering inline: "deploy jar, then DB cleanup; wrong order = silent data loss."
- Every state-changing procedure names its rollback, or states plainly that none exists and what that means. A missing undo path is a finding, not an omission the reader discovers mid-incident.
- End with a "verify it worked" section: the observable end state and the command that proves it.
- Mark the preferred path "(recommended)" when several paths exist; document UI and CLI for the same task side by side rather than twice.
- If the runbook will shrink when tooling lands, say so: "when X lands, steps 2 to 4 become one command and this document keeps only the judgment."
Troubleshooting entries
Symptom-first, because the reader arrives with an error message and no vocabulary:
markdown
## <symptom as the user sees it>
**Symptom**: verbatim error strings (searchable)
**Cause**: ...
**Fix**: exact commands
Order diagnostic steps cheapest first. Group entries by failure class. Cross-link the deeper doc instead of inlining it.
Migration and deprecation guides
A migration guide is a runbook whose subject is the change itself. Everything above applies, plus five rules of its own. The surrounding documents are handled by their own skills: the argument for the migration is a design doc, the decision to deprecate is an ADR, the announcement is a changelog entry; this section is the guide the reader executes.
- History is the content here, stated positively. The before/after comparison is the job, not a violation: this is the document class the no-history hard rule explicitly carves out. Write "the tag now replaces the manual version bump" freely; that sentence is banned everywhere else and load-bearing here.
- The mapping table is the core artifact. Readers arrive knowing the old world; give them old → new per behavior, config key, command, or API, one row each. Prose explains the rows that need it; the table carries the migration.
- Rollback is mandatory, per step. Every step names its undo, or states plainly that it is irreversible and what that means for the ordering around it. A migration guide without rollback paths is a proposal to strand people mid-migration.
- The deprecation contract carries dates. What stops working, on which date, what happens to stragglers, and where the escape hatch is until then. "Will be removed in a future release" is a banned vague owner wearing a calendar.
- Born with an expiry. A migration guide is temporary by design: when the migration completes, it reclassifies as historical and gets the superseded banner pointing at the current-state documentation, never silent deletion. State the completion condition in the guide itself.
Operator-facing strings
Error messages and log lines are runbook prose with the shortest reading window: keep remediation specific and actionable, and make error states visible rather than letting workflows appear healthy.