| name | runbook-generator |
| description | Generate an operational runbook for a service — covering deploy/rollback, common incidents, on-call escalation, SLOs, dashboards, and dependencies. Use when the user is launching a new service, onboarding to on-call, or being asked for "the runbook" by SRE or production-readiness review. |
runbook-generator
You help the user produce a runbook that a sleep-deprived on-caller at 3am can actually use.
How to respond
-
Understand the service. Before drafting, you need:
- Service name + one-line purpose ("
payments-api — handles checkout and refund requests")
- Owners (team + escalation chain)
- Tech stack (language, runtime, storage, message brokers)
- Deployment surface (Kubernetes namespace, ECS cluster, Lambda, …)
If multiple of these are missing, ask. A runbook with placeholders for owner + escalation is worse than no runbook.
-
Use templates/runbook.md as the skeleton — it has sections roughly in the order an on-caller will actually need them at 3am (current incidents first, then how to deploy/rollback, then deeper context last).
-
Bias toward concrete commands over prose. "Restart the pods" → kubectl rollout restart deployment/payments-api -n payments. The runbook should be paste-able.
-
Cover the "common 5" incidents. Every service has ~5 failure modes that account for 80% of pages. Cover each with: how to recognize it, immediate mitigation, root-cause investigation step, and when to escalate.
If the user can't list 5, ask: "what's caused the most pages over the last quarter?" The honest answer is the most valuable section of the runbook.
-
Link, don't inline. Dashboards, error budgets, change calendars, alert definitions — these live elsewhere and shouldn't be duplicated. Link with a one-line description so the on-caller knows what they'll find.
Quality bar
- Owner info is current. Use roles ("payments-platform team, primary on-call rotation") rather than individual names that go stale when people change teams.
- Every alert listed has a response. A "what to do when this alert fires" section that doesn't cover all the alerts is worse than no section.
- Rollback is one command, or three steps max. If rollback is complicated, write a script and link to it.
- No "TBD" left in the doc when it's published. Move TBDs to a "known gaps" section so they're explicit, not hidden.
Anti-patterns to avoid
- ❌ Architecture diagrams in the runbook. (Link to the design doc instead — they go stale faster than the runbook does.)
- ❌ Long backstory before the operational commands.
- ❌ "Page X if you're not sure" without saying what X knows that you don't.
- ❌ Listing every metric Prometheus has. Pick the 5–10 that actually predict outages.
