runbooklisted

# Runbook A runbook is executable by a tired stranger with no context. If it needs the author present, it is not a runbook — it is notes. ## Template ```markdown # Runbook: <alert or procedure name> ## What this means <The user-visible symptom in one sentence. Not the metric — the symptom.> ## Severity and impact <Who is affected, how badly, how fast it escalates if ignored.> ## Diagnosis 1. <exact query, dashboard link, or command — copy-pasteable> - <output A> → cause 1, go to Mitigation row 1 - <output B> → cause 2, go to Mitigation row 2 ## Mitigation | Symptom | Action | Command | Risk | ## Escalation <Who, by which channel, after how long, and what to tell them.> ## Rollback <Exact steps, and how to confirm it worked.> ## Related <Dashboards, ADRs, past incidents.> ``` ## Worked example Two versions of one diagnosis step: **Useless at 3am:** ```markdown ## Diagnosis 1. Check if the database is healthy. 2. Look at the connection pool. 3. Restart the service if needed. ``` Every line raises a question the on-call engineer cannot answer alone. *Which* database? Healthy by what measure? Restart how, and what breaks when they do? **Executable at 3am:** ```markdown ## Diagnosis 1. Is the pool saturated? ``` kubectl exec -n prod deploy/api -- \ psql $DB_URL -c "select count(*), state from pg_stat_activity group by state" ``` - `active` ≥ 95 (pool max is 100) → **saturated**, go to Mitigation row 1 - `idle in transaction` ≥ 20 → **leak