Runbook

---
name: runbook
description: "Generate an operations runbook from your deployment config, Docker/K8s manifests, CI/CD pipelines, and monitoring setup. Produces copy-pasteable procedures for deployment, rollback, scaling, database maintenance, incident response, and troubleshooting. Use when you need a runbook, ops playbook, deployment guide, incident response plan, or production operations documentation."
version: "2.0.0"
category: docs
platforms:
  - CLAUDE_CODE
---

You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project's
infrastructure and operations artifacts to produce a comprehensive runbook.

INPUT:
$ARGUMENTS

Accepted arguments:
- No arguments: generate a complete operations runbook.
- `deployment`: focus on deployment procedures only.
- `incident`: focus on incident response procedures only.
- `database`: focus on database maintenance procedures only.
- `troubleshooting`: focus on troubleshooting guides only.

============================================================
PHASE 1: INFRASTRUCTURE DISCOVERY
============================================================

Step 1.1 -- Deployment Configuration

Scan for deployment artifacts:

| Type | Files to Check |
|------|---------------|
| Docker | Dockerfile, docker-compose.yml, docker-compose.*.yml |
| Kubernetes | k8s/, kubernetes/, manifests/, *.yaml with `apiVersion:` |
| Helm | Chart.yaml, values.yaml, templates/ |
| Terraform | *.tf, terraform/, infrastructure/ |
| Serverless | serverless.yml, SAM template.yaml |
| PaaS | Procfile, fly.toml, vercel.json, netlify.toml, app.yaml |
| PM2 | ecosystem.config.js |

Step 1.2 -- CI/CD Pipeline

Scan for: `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`,
`.circleci/config.yml`, `bitbucket-pipelines.yml`, `cloudbuild.yaml`,
`azure-pipelines.yml`.

Read each pipeline file and extract build steps, deployment targets,
environment variables, secrets referenced, and branch triggers.

Step 1.3 -- Database Configuration

Scan for: migration files (migrations/, prisma/migrations/, alembic/, db/migrate/),
schema files (schema.prisma, models.py, *.entity.ts), seed files, database config
(database.yml, knexfile.js), and backup scripts.

Step 1.4 -- Monitoring and Observability

Scan for: logging config (winston, pino, log4j), APM (newrelic, datadog, elastic-apm),
metrics (prometheus, grafana), error tracking (sentry, bugsnag, rollbar),
health check endpoints, and alerting rules.

Step 1.5 -- Environment Configuration

Scan for: .env.example, environment-specific configs, feature flags, and
secrets management (vault, AWS SSM, sealed secrets).

============================================================
PHASE 2: RUNBOOK GENERATION
============================================================

Generate `docs/runbook.md` with these sections. Only include sections relevant
to detected infrastructure. Every procedure must have copy-pasteable commands.

The runbook MUST cover these areas (skip if not applicable to project):

1. **Deployment** -- Prerequisites, step-by-step deploy commands per environment,
   post-deploy verification checklist (health check, logs, smoke test, metrics).

2. **Rollback** -- Quick rollback procedure (< 5 min, redeploy previous version),
   full rollback with database revert if needed, verification checklist.

3. **Scaling** -- Scale up/down commands, auto-scaling config and thresholds.

4. **Database Maintenance** -- Run/rollback migrations, create/restore backups,
   common diagnostic queries (table sizes, active connections, slow queries).

5. **Incident Response** -- Severity levels (SEV1-4 with response times and examples),
   incident checklist (acknowledge, communicate, investigate, mitigate, resolve, postmortem),
   first-response diagnostic commands for logs, status, and resources.

6. **Monitoring** -- Dashboard links, key metrics with normal ranges, alert response
   guide (high CPU, memory, error rate, disk, health check failures with actions).

7. **Troubleshooting** -- Common failure scenarios (app won't start, connection timeouts,
   performance degradation) with step-by-step diagnosis. Error-to-solution lookup table.

Format: use markdown headers, numbered steps with fenced bash blocks for commands,
checklists for verification, and tables for reference data.

If a runbook already exists, read it first and preserve manually-written sections.

============================================================
PHASE 3: VALIDATE AND WRITE
============================================================

For each command in the runbook:
- Verify the referenced tool/CLI exists in the project's dependencies or Dockerfile
- Verify paths and file references are correct
- Verify environment variable names match what the project uses

Write the runbook to `docs/runbook.md`.


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:
- Identify which sections are incomplete or contain placeholders
- Re-generate only the deficient sections
- Repeat up to 2 iterations

============================================================
OUTPUT
============================================================

## Runbook Generated

### Infrastructure Detected
- **Deployment:** [Docker / K8s / Serverless / etc.]
- **CI/CD:** [GitHub Actions / GitLab CI / etc.]
- **Database:** [PostgreSQL / MongoDB / etc.]
- **Monitoring:** [Datadog / Prometheus / etc.]
- **Environments:** [dev, staging, production]

### Sections Generated
- [ ] Deployment procedures
- [ ] Rollback procedures
- [ ] Scaling instructions
- [ ] Database maintenance
- [ ] Incident response
- [ ] Monitoring and alerts
- [ ] Troubleshooting guide

### File Written
- `docs/runbook.md`


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /runbook — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================
DO NOT
============================================================

- Do NOT fabricate infrastructure details. Only document what is evident from config files.
- Do NOT include actual secrets, passwords, or API keys in the runbook.
- Do NOT include placeholder commands for infrastructure that does not exist.
- Do NOT generate a runbook for projects with no deployment configuration
  (e.g., a library or CLI tool). Report that no runbook is needed and suggest `/readme`.
- Do NOT include generic advice not specific to this project's stack.

NEXT STEPS:

After generating the runbook:
- "Run `/document` to check overall documentation health."
- "Run `/diagram` to generate infrastructure diagrams."
- "Run `/devops` to review and improve the deployment pipeline."