Runbook Writer

Operational runbooks written during an incident or from memory are often vague, dangerous, or missing critical branches. When responders are paged at 3am, they need exact commands, clear warnings, and verified signals rather than "investigate further." This skill transforms raw alert definitions, incident postmortems, and rough notes into structured, safety-first operational guides.

What it does

• Alert Inventorying scans Prometheus, CloudWatch, and Datadog definitions to scaffold runbook stubs for every firing alert.
• Incident Synthesis converts postmortem threads and chat logs into generalized procedures that address failure classes.
• Safety-First Drafting prioritizes read-only triage, mandates rollback steps, and places warnings before any state-changing command.
• Automated Linting flags vague instructions, missing escalation paths, and risky commands lacking explicit approval steps.
• Gap Identification explicitly marks missing operational facts as TO CONFIRM items rather than making dangerous guesses.

How it works

1. Source Analysis where you provide alert YAMLs, incident logs, or existing wiki pages for the agent to ingest.
2. Drafting using a standardized template that separates diagnosis, mitigation, verification, and escalation.
3. Internal Review where the agent lints the draft against strict operational writing standards to remove ambiguity.
4. Handoff providing a list of untested commands and a categorized list of questions for specific stakeholders.

Frameworks & tools

This skill uses Python scripts for static analysis of PrometheusRule objects, CloudWatch alarm exports, and Datadog monitor JSON. It follows SRE best practices for incident response and operational documentation.

Why this beats prompting it yourself

Standard LLM prompts often hallucinate plausible-looking but incorrect CLI flags or omit crucial "what if this fails" branches. This skill enforces a "no-guesswork" policy, ensuring that every command and threshold is sourced directly from your infrastructure code or explicitly marked for verification.

Use cases

• Scaffolding documentation for a new service by scanning its Prometheus alert rules.
• Converting a Slack incident thread into a permanent, reusable playbook for future responders.
• Auditing existing runbooks to find missing rollback procedures or outdated escalation contacts.
• Hardening on-call guides by adding "Expected Result" checks to every manual step.

Known limitations

The agent cannot execute commands or verify them against a live environment. It reads static alert definitions but does not expand complex YAML anchors, templates, or dynamically generated rules.