Runbook Generator

Overview

Core Capabilities

• Runbook skeleton generation from a CLI
• Standard sections for start/stop/health/rollback
• Structured escalation and incident handling placeholders
• Reference templates for deployment and incident playbooks

When to Use

• A service has no runbook and needs a baseline immediately
• Existing runbooks are inconsistent across teams
• On-call onboarding requires standardized operations docs
• You need repeatable runbook scaffolding for new services

Quick Start

# Print runbook to stdout
python3 scripts/runbook_generator.py payments-api

# Write runbook file
python3 scripts/runbook_generator.py payments-api --owner platform --output docs/runbooks/payments-api.md

Recommended Workflow

1. Generate the initial skeleton with

   scripts/runbook_generator.py

   .
2. Fill in service-specific commands and URLs.
3. Add verification checks and rollback triggers.
4. Dry-run in staging.
5. Store runbook in version control near service code.

Reference Docs

• references/runbook-templates.md

Common Pitfalls

• Missing rollback triggers or rollback commands
• Steps without expected output checks
• Stale ownership/escalation contacts
• Runbooks never tested outside of incidents

Best Practices

1. Keep every command copy-pasteable.
2. Include health checks after every critical step.
3. Validate runbooks on a fixed review cadence.
4. Update runbook content after incidents and postmortems.