Runbook Generator

---
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

1. **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.

2. **Use [`templates/runbook.md`](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).

3. **Bias toward concrete commands over prose.** "Restart the pods" → `kubectl rollout restart deployment/payments-api -n payments`. The runbook should be paste-able.

4. **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.

5. **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.