Skip to content

Runbook Template

Copy this template to docs/runbooks/<symptom>.md whenever you add a runbook. Keep every section concrete and tested — a runbook is only as good as the last time it was executed.

# Runbook: <Symptom / Incident Name>

## Overview

One paragraph: what is happening, what is affected, severity.

## Detection

Signals that indicate this incident:

- log patterns / error codes
- metric or dashboard names
- user-reported symptoms

## Initial assessment

Up to 5 yes/no or quick commands that separate root causes:

```text
Is X reachable?  → cmd
Is Y healthy?    → cmd
Is it global?    → check
```

Fix

1.

Commands, config changes, who to involve.

2.

…

Verification

How to confirm the fix worked (checks, dashboards, sample request).

Escalation

Threshold for paging who and at what point.

---

## Rules

- **Step-by-step and tested** — never aspirational prose.
- Include real commands with placeholders like `$HOST`.
- One runbook per distinct symptom; cross-link related ones.
- Update it in the same incident if a step was wrong.

## Checklist

- [ ] Detection signals listed
- [ ] Commands are copy-paste safe
- [ ] Escalation criteria defined
- [ ] Verification section present
- [ ] Cross-links to related docs resolve