What this template is for
A runbook entry is the operational analogue of a unit test - it captures exactly one failure mode and exactly what to do about it. Teams that operate well in production have dozens of runbook entries, each tight and tested. Teams that operate poorly have one giant wiki page that nobody reads because nothing in it is current.
This template enforces the one-alert-one-runbook discipline. Every entry has the same shape: symptom, diagnosis, mitigation, verification, escalation.
When to use it
Create a runbook entry whenever:
- A new alert is added to the monitoring stack
- A postmortem identifies an action whose mitigation is not yet documented
- A novel failure mode is debugged by the on-call (don’t let that knowledge stay in a slack thread)
- A chaos drill exposes a gap in existing documentation
Sub-task breakdown
The last sub-task - schedule a 90-day review and an annual chaos test - is the one that decides whether the runbook stays accurate. STM Issue Templates makes it automatic: the review sub-task is created on every new runbook ticket and surfaces in the on-call queue 90 days later. Untested runbooks are the rule, not the exception, and STM is the cheapest way to fight that drift.
Fields to add to your Jira create screen
These are the fields a project admin should make sure exist on the Create Issue screen for this issue type (Project settings → Screens). Without these on the screen, reporters can't provide the information triage needs - and STM can't reference them either.
| Field | Example value | Required |
|---|---|---|
Summary | Runbook RB-118 - payments-svc p99 latency alert | Yes |
Runbook ID (custom) | RB-118 | Yes |
Alert / Symptom (custom) | Alert payments-svc-p99 fires when p99 > 800ms for 5m | Yes |
Service | payments-svc | Yes |
Diagnosis Steps (custom) | 1. Check Grafana dashboard. 2. Check DB connection pool. 3. ... | Yes |
Mitigation Steps (custom) | 1. Scale out replicas. 2. Failover DB if pool exhausted. | Yes |
Verification (custom) | p99 returns below 500ms; alert auto-resolves within 10m | Yes |
Escalation Path (custom) | If unresolved in 30m: page @platform-lead | Yes |
Last Tested (custom) | 2026-05-10 (chaos drill) | No |
Owner | @alex.chen | No |
Related Dashboards | https://grafana.example.com/d/payments | No |
Labels | runbook, payments | No |
Note on custom fields. STM currently supports up to 5 custom fields per template. You can add as many custom fields as you like to your Jira Create Issue screen - the 5-field limit only applies if you want STM to set or update those custom fields itself.
Sub-tasks STM creates automatically
Build an STM sub-task template containing the items below, then wire it to an On Create Issue Executor scoped to this issue type. Whenever a new issue of this type is created in the project, STM creates the full sub-task set in one step - with assignee, due date, and components inherited from the parent unless you override them.
- Draft symptom and diagnosis steps from a real or simulated incident
- Confirm mitigation steps with the service owner
- Review with the on-call rotation and capture edge cases
- Link the runbook from the alert annotation in Grafana/PagerDuty
- Schedule a 90-day review and a once-per-year chaos test of the runbook
Common questions
What is a runbook entry?
A runbook entry is the documented procedure for one alert or failure mode: the symptom you see, the diagnosis steps that confirm the cause, the mitigation actions that resolve it, and the verification that confirms recovery. A good runbook reads like a checklist, not an essay - the on-call should be able to follow it under stress at 03:00.
Should runbooks live in Jira or a wiki?
Both, but the source of truth should be searchable from where the on-call already is. Storing the canonical runbook as a Jira ticket means it shows up in the same search as incidents and changes, and it can be linked directly from alert annotations. A wiki render is fine for browsing; the Jira ticket is the editable source.
How do you keep runbooks from going stale?
Two practices. First, every postmortem either updates a runbook or files a sub-task to do so. Second, schedule a 90-day review on every runbook ticket - [STM Issue Templates](/stm/) can auto-create that review sub-task so it cannot be silently skipped. Runbooks that are not tested are wishful thinking.
What format should a runbook entry use?
Symptom, diagnosis, action, verification, escalation. Numbered steps under each heading. Avoid prose; the reader is the on-call engineer who is trying to fix something, not a new joiner who wants to understand the system. Keep one runbook entry per alert; if an alert has two distinct causes, split it into two runbooks.
Automate the sub-tasks with STM
STM Issue Templates saves the sub-task list above as a reusable template and creates them on every new issue of this type - via an Executor on issue creation, on status transition, or triggered manually from the issue's "Create bulk sub-tasks" menu. STM does not change the parent issue's create screen (that's a Jira project-settings job) but it removes the manual work of creating the sub-tasks every time.
Try STM on the Atlassian Marketplace ↗ See how STM templates are built →