brianpelow/runbook-gen

runbook-gen

Auto-generates operational runbooks from code, alerts, and incident history using AI.

Overview

runbook-gen eliminates the most neglected part of operational readiness — writing runbooks. It reads your code comments, alert definitions, and past incident data and generates structured operational runbooks using Claude.

Built for engineering teams in regulated financial services, fintech, and manufacturing where runbooks are a compliance requirement under frameworks like FFIEC, SOX, and IEC 62443 — not just operational good practice.

Quick start

pip install runbook-gen

# Generate a runbook from a service directory
runbook-gen generate src/payments_service/ --output runbooks/

# Generate from an alert definition file
runbook-gen from-alerts alerts/critical.yml --output runbooks/

# Generate from past incident data
runbook-gen from-incident incidents/INC-2024-047.md --output runbooks/

# Export a runbook to Confluence

## Commands

| Command | Description |
|---------|-------------|
| `runbook-gen generate` | Generate runbook from a service directory |
| `runbook-gen from-alerts` | Generate from alert definition files |
| `runbook-gen from-incident` | Generate from past incident markdown |
| `runbook-gen export` | Export runbook to Markdown or Confluence |
| `runbook-gen validate` | Validate a runbook against compliance standards |

## Generated runbook format

# Service Name — Operational Runbook

## Service overview
## On-call contact
## Architecture diagram
## Common alerts and responses
## Step-by-step remediation procedures
## Escalation paths
## Rollback procedures
## Compliance notes
## Revision history

Configuration

| Variable | Description | Required | |----------|-------------|----------| | ANTHROPICAPIKEY | Claude API key for generation | Yes | | CONFLUENCEURL | Confluence base URL for export | No | | CONFLUENCETOKEN | Confluence API token | No | | RUNBOOKINDUSTRY | Industry context (fintech/manufacturing) | No |

Industry context

In regulated environments, runbooks serve as evidence of operational controls. runbook-gen produces runbooks aligned with:

• Fintech: FFIEC IT examination handbooks, SOX ITGC controls, PCI-DSS
• Manufacturing: IEC 62443 operational procedures, ISO 9001 work instructions

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE.