Start with a 10-minute extraction pass
On-call handoff notes are usually readable but not runnable. The quickest fix is a focused extraction pass that turns narrative updates into structured inputs you can visualize.
Collect the raw inputs
- Last 1–3 handoff notes for the same service or incident type
- One recent postmortem link if available
- Pager or ticket fields: service, severity, timestamps, current state
Convert prose into five buckets
Copy the handoff notes into a scratch doc and rewrite only what matters into these buckets:
- Symptoms: what the on-caller sees (alerts, dashboards, user impact)
- Checks: how to confirm the symptom (commands, queries, dashboards)
- Likely causes: common failure modes mentioned in past handoffs
- Actions: mitigations that were tried (and whether they worked)
- Owners: which team/person can change what (app, infra, vendor)
Do not polish. You are building a runbook spine that you will map into a flow.
Map dependencies in 10 minutes using a “what must be true” chain
Dependency-aware runbooks are faster because they prevent random walks. You want the operator to follow a chain of constraints: “If this is failing, what upstream condition must be true?”
Build a dependency list from the notes
From your buckets, extract a simple dependency inventory. Keep each dependency to a noun phrase:
- Ingress / CDN
- Auth / token service
- Primary API
- Queue / stream
- Database
- Third-party provider
Turn the inventory into a chain
For each dependency, write one sentence:
- What indicates it’s broken? (signal)
- What depends on it? (downstream)
- Who owns it? (owner path)
This creates a runnable graph: signals point to checks; checks point to actions; actions point to owners.
Draft the flowchart in 10 minutes with a fixed node template
The runbook becomes useful when every node looks the same. Consistency is what makes it scannable at 3 a.m.
Use five node types only
- Trigger: “Alert fires / user impact reported / SLO burn”
- Decision: “Is error rate above X for Y minutes?”
- Check: “Run query / open dashboard / inspect logs”
- Action: “Rollback / scale / fail over / disable feature flag”
- Escalation: “Page team / open vendor ticket / declare incident”
Write nodes in operator language
Each node should fit on one screen without scrolling. Prefer imperative verbs and concrete thresholds. Avoid “investigate” unless you include what to look at and what “good” vs “bad” means.
If you want to convert your text into a clean diagram quickly, paste the structured nodes into napkin.ai and generate a flowchart you can adjust without redesigning it from scratch.
Add escalation triggers and owner paths in 5 minutes
Most runbooks fail because they hide escalation. Handoff notes often include “we pinged X” or “vendor was slow,” but not when to do it. Make escalation explicit and time-bound.
Define escalation as a first-class branch
For any decision point, add an escalation branch when one of these is true:
- Time trigger: no improvement after N minutes of the primary mitigation
- Blast-radius trigger: multiple services impacted or core customer flows down
- Control trigger: you lack permissions or it’s owned elsewhere
- Risk trigger: action could cause data loss or extended downtime
Make owner paths unambiguous
Each escalation node should include:
- Who: team name and on-call rotation
- Channel: page, Slack channel, phone bridge, vendor portal
- What to send: a tight payload (symptom, scope, timestamps, links)
This is where your issue intake process matters: consistent escalation payloads reduce back-and-forth. If you need a lightweight structure for turning pings into a single queue, adapt an issue intake contract so escalations land with context and priority.
Do a 5-minute validation pass against real handoffs
Before you publish the runbook flowchart, validate it against what actually happens during on-call.
Test three scenarios
- Happy path: alert triggers → checks confirm → mitigation works
- Ambiguous signal: checks disagree → alternate branch resolves
- Blocked operator: permissions/vendor/unknown cause → escalation path is clear
Look for the common failure points
- Decisions without thresholds (“high latency” with no number)
- Actions without rollback guidance
- Checks that require tribal knowledge (missing query, missing dashboard link)
- Owner paths that skip the real gatekeeper
If your input notes contain sensitive identifiers, redact before you operationalize them. Use a repeatable redaction approach that preserves searchability so the runbook stays discoverable later; the meeting notes redaction playbook is a practical model for doing this without losing useful context.
What the finished runbook flow should include
After 40 minutes, you should have one dependency-aware flowchart per service or per high-frequency incident pattern. The minimum viable output is:
- A clear trigger node tied to alert names or user-impact signals
- A dependency-ordered set of checks (upstream before downstream)
- Decision points with numeric thresholds and time windows
- Mitigation actions with safety notes and rollback options
- Escalation triggers that are time-bound and risk-aware
- Owner paths that specify who, where, and what to send
This format turns handoff notes from “what happened last night” into “what to do next,” while preserving the dependency context that prevents wasted cycles.
