runbook-writing-weapon

Operational runbook craft: the exact-command discipline, the no-implied-context rule, escalation path architecture, rollback procedures, runbook-as-test methodology, and postmortem-to-runbook linkage.

Read this file first to orient. Then open the guide that matches your task.

The five core principles

These govern every decision in this weapon. Full justification with failure modes per principle in guides/00-principles.md.

1. No implied context. Every command is copy-pasteable. Every URL is absolute. Every env var is defined. Every decision point is explicit. A runbook written for "someone who knows the system" is not a runbook.
2. Exact-command discipline. No "something like kubectl get pods." Exact flags, exact namespaces, exact service names. Vague commands create incident-time variance.
3. Explicit escalation paths. Every runbook names its escalation contact (person, team, channel) with a response-time expectation. "Escalate if needed" is not an escalation path.
4. Rollback before you ship. Every state-changing step has an undo step or an explicit irreversibility acknowledgment. Rollback is never improvised during an incident.
5. Runbook-as-test mandate. An untested runbook is a hypothesis. Exercise runbooks quarterly (game day) and on every postmortem action item. Mark untested runbooks prominently.

Research anchor: Google SRE Book Chapter 11 defines on-call as requiring co-equal resources: clear escalation paths, well-defined procedures, and blameless postmortem culture. All five principles map directly to this triad. See research/external/2026-sre-google-being-on-call-chapter.md.