Skill: charlie-morrison/runbook-automator (version 1.0.1)

--- name: runbook-automator description: Convert manual incident runbooks into automated, executable playbooks. Parse existing runbooks, generate scripts for each step, add health checks, rollback procedures, and notification hooks. --- # Runbook Automator Transform manual runbooks into automated, executable playbooks. Parse existing documentation, generate step-by-step scripts with health checks, decision points, rollback procedures, and notification hooks — so incidents get resolved faster with less human intervention. Use when: "automate this runbook", "convert runbook to script", "make this playbook executable", "incident automation", "turn this wiki page into a script", or when building on-call automation. ## Commands ### 1. `convert` — Parse Runbook and Generate Automation #### Step 1: Identify Runbook Format Read the input runbook (markdown, Confluence wiki, Google Doc, plain text) and extract: - **Title and scope** — what incident does this address - **Prerequisites** — access, tools, permissions needed - **Steps** — ordered actions (distinguish manual vs automatable) - **Decision points** — if/then branches - **Verification steps** — how to confirm each step worked - **Rollback steps** — how to undo if things go wrong - **Escalation criteria** — when to page someone #### Step 2: Classify Each Step For each step in the runbook, classify as: | Type | Example | Automation | |------|---------|------------| | **Command** | "Run `kubectl rollout restart`" | Direct script execution | | **Check** | "Verify pods are running" | Script with assertion | | **Decision** | "If error rate > 5%, proceed to step 4" | Conditional branch | | **Manual** | "Call the database team" | Notification + pause | | **Observation** | "Watch the dashboard for 10 minutes" | Timed wait + metric check | #### Step 3: Generate Executable Playbook ```bash #!/usr/bin/env bash set -euo pipefail # ============================================ # Automated Runbook: [Title] # Generated from: [source document] # Last updated: [date] # ============================================ SLACK_WEBHOOK="${SLACK_WEBHOOK:-}" PAGERDUTY_KEY="${PAGERDUTY_KEY:-}" DRY_RUN="${DRY_RUN:-false}" log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; } notify() { log "NOTIFY: $1" if [[ -n "$SLACK_WEBHOOK" ]]; then curl -s -X POST "$SLACK_WEBHOOK" -H 'Content-Type: application/json' \ -d "{\"text\": \"🔧 Runbook: $1\"}" > /dev/null fi } fail() { notify "❌ FAILED at step $1: $2"; exit 1; } # --- Step 1: [Name] --- step_1() { log "Step 1: [description]" if [[ "$DRY_RUN" == "true" ]]; then log "DRY RUN: would execute [command]" return 0 fi # [actual command] [command] || fail 1 "[error description]" # Verify [verification command] || fail 1 "Verification failed" log "Step 1: ✅ Complete" } # --- Step 2: [Decision Point] --- step_2() { log "Step 2: Checking [condition]" local metric metric=$([check command]) if (( $(echo "$metric > 5" | bc -l) )); then log "Threshold exceeded ($metric > 5) — escalating" step_2a # escalation path else log "Within bounds ($metric <= 5) — continuing" step_3 fi } # --- Rollback --- rollback() { notify "🔄 Rolling back..." log "Rollback: [undo commands]" [rollback command 1] [rollback command 2] notify "Rollback complete" } trap 'rollback' ERR # --- Execute --- notify "Starting runbook: [Title]" step_1 step_2 # ... remaining steps notify "✅ Runbook complete" ``` ### 2. `analyze` — Audit Existing Runbooks for Gaps Read all runbooks in a directory and flag: ```bash # Find runbook-like documents find . -maxdepth 3 \( -name "*.md" -o -name "*.txt" -o -name "*.adoc" \) | \ xargs grep -li "runbook\|playbook\|incident\|on-call\|troubleshoot" 2>/dev/null ``` For each runbook, check: - **Missing rollback steps** — what happens if step 3 fails? - **No verification** — steps that say "do X" but never check if X worked - **Stale commands** — references to deprecated tools, old hostnames, removed services - **Missing decision criteria** — "if it's bad, escalate" (how bad? what metric?) - **No estimated time** — SLA-critical runbooks need time bounds per step - **Missing prerequisites** — assumed access or tools not listed Output a coverage report: ```markdown # Runbook Audit Report | Runbook | Steps | Automated | Rollback | Verified | Gaps | |---------|-------|-----------|----------|----------|------| | DB Failover | 8 | 3/8 (38%) | ✅ | 5/8 | Stale hostname in step 4 | | API Scale-Up | 5 | 5/5 (100%) | ❌ Missing | 4/5 | No rollback procedure | | Cache Flush | 3 | 2/3 (67%) | ✅ | 3/3 | Step 2 references removed tool | ``` ### 3. `test` — Dry-Run a Generated Playbook Execute the generated script with `DRY_RUN=true`: - Validate all commands exist in PATH - Check prerequisite access (can reach hosts, have credentials) - Verify notification hooks work (send test message) - Estimate execution time based on sleep/wait steps - Flag any steps that would require manual intervention ### 4. `template` — Generate Runbook Template Given an incident type (database, network, application, security), generate a structured template with: - Standard sections (scope, impact, prerequisites, steps, rollback, escalation) - Common steps for that incident type pre-filled - Placeholder verification commands - Notification hooks - Post-incident review checklist


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)