Skip to main content

Runbook authoring

The authoring standard that completes the runbook template: who writes runbooks (skills draft, humans verify), what every runbook must contain, how steps are marked agent-executable versus human-only, and how runbooks stay current. A runbook is the artefact Support trusts at 3am — the rules here exist so that trust is earned.

Skills draft, humans verify​

  • The first draft is generated — a runbook-generation skill drafts from the code, the pipeline config and the observability setup during Build. Writing runbooks by hand from scratch is exactly the kind of work agents should do.
  • The service owner verifies every step before v1.0. Run the diagnostics, follow the recovery procedure, confirm the dashboard links resolve. An unverified runbook is worse than none, because it will be trusted under pressure.
  • Runbooks live in-repo (docs/runbooks/, per repo context & memory) and update in the same PR as any change that alters operational behaviour (docs-with-build) — a runbook maintained separately from the code is stale by construction.

Required sections​

Every runbook carries the template's sections, none optional: overview (what it does, dependencies), dashboards & alerts (what each alert means), diagnostics (stepwise, each step marked per below), known failure modes (symptom → cause → action, each row linked to its gotcha in memory/), escalation (who, when, severity thresholds per the rapid-fix SLAs), and recovery (backup/restore and rollback, with verification). A runbook missing a section is not accepted at handover.

Marking rules: agent-executable vs human-only​

  • Every diagnostic and recovery step is marked with the template's agent-executable or human-only mark. Unmarked steps are treated as human-only.
  • The default is human-only. A step earns the agent-executable mark by being read-only or trivially reversible — gathering logs, querying a dashboard, running a health check.
  • Anything irreversible is human-only, always: production restarts, failover, data changes, key rotation, anything on the authorise-the-irreversible list. An agent may prepare such a step (stage the command, draft the change) — only a named human executes it.
  • Marks are reviewed by the service owner, never assigned by the drafting skill alone. The marking is a permission boundary, so it's reviewed like one.

Currency​

  • Flow-state checks runbook currency every loop (playbook): every operational lesson becomes a runbook step, stale steps are pruned, and the escaped-defect loop deposits a known-failure row per production defect.
  • Support resolutions update runbooks at ticket closure per the KCS loop — the same fix is never re-derived.

Handover​

Runbooks are handed to Support at the Production Readiness gate — and Support accepts them, which means walking the diagnostics, not receiving a link (support playbook). Acceptance is an exit criterion of the gate; ownership rules thereafter follow the staffing model.

Standards referenced: Google SRE (playbooks/runbooks), ITIL 4, Diátaxis (how-to form).

Last updated on