Runbook Generator

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.

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

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

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sananthanarayan
• Source: sananthanarayan/skilldrop
• License: MIT

Install and usage instructions live in the source repository linked above.