Runbook from Postmortem

What this skill does

Reads an incident postmortem and emits a runbook table where each row links a specific alert condition to a specific mitigation step. Avoids prose: a tired on-call should be able to scan rows and execute commands.

Inputs

• postmortem_path: markdown file with the postmortem.
• runbook_dir: target directory (typically docs/runbooks/).
• Optional service_name: the service the runbook governs; otherwise inferred from the postmortem title.

Steps

1. Read the postmortem and extract: timeline events, detection signal (alert name), root cause, mitigation actions taken, follow-up action items.
2. Identify alert conditions used or newly proposed. Quote them in their monitoring-system DSL (PromQL, Datadog, CloudWatch).
3. For each alert condition, locate the corresponding mitigation in the timeline. The mitigation should be a single shell command or a 2-3 step command sequence.
4. Where the postmortem describes a remediation but no alert, propose an alert condition based on the metric mentioned (e.g., "p99 latency > 2s for 5m").
5. Compose a markdown table with columns: Alert, Symptom, Mitigation, Owner, Escalation. One row per alert condition.
6. Add a "Diagnostic Commands" section: 5-10 read-only commands (e.g., kubectl logs, psql -c 'select ...') gathered from the timeline.
7. Add a "Known Pitfalls" section: 2-4 bullets pulled from "what made this hard" parts of the postmortem.
8. Add cross-links: at the top, link to the postmortem; at the bottom, link to upstream service docs.
9. Save the file as <runbook_dir>/<service-name>-<incident-tag>.md.

Output

A new runbook file at <runbook_dir>/... containing the table, the diagnostic commands, the pitfalls, and cross-links. Print a summary to stdout listing the row count, alert count, and any postmortem action items not yet covered.

Verification

Re-read the saved runbook and confirm every row has a non-empty Mitigation cell — empty cells defeat the purpose. Cross-check that each alert in the table appears verbatim in the monitoring-system config (run rg "<alert name>" <repo_dir>/monitoring/); flag any orphan alerts. Run a dry-run of the first diagnostic command to ensure syntactic validity (e.g., kubectl --dry-run=client).

Edge cases

• Postmortem with no clear root cause: emit a runbook with diagnostic commands only and a "investigation-only" status banner.
• Multiple incidents merged into one postmortem: produce one runbook per distinct root cause.
• Mitigation requires manual coordination (e.g., calling a vendor): record contact info in the Escalation column rather than pretending it's automatable.
• Postmortem older than 12 months: prepend a freshness warning; details may be stale.