---
name: runbook-drafter
description: Convert plain-English incident descriptions, postmortem notes, and operations procedures into structured runbooks, incident reports, and postmortem documents.
---

## Trigger Phrases
Use this skill when the request is to write, structure, or improve operational documentation:

- "Turn this incident description into a runbook."
- "Write a postmortem for this outage."
- "Draft a runbook for restarting the payment service."
- "I fixed this issue — help me document what I did."
- "Create an on-call procedure for database failover."
- "Write an SOP for rotating API keys."

Do not use this skill for documentation that is primarily code-focused (like API reference). Use for operational procedures, incident documentation, and on-call guides.

## Deterministic Execution Flow

### Stage 0: Classify Document Type

| Type | User intent | Output format |
|------|-------------|---------------|
| `runbook` | Step-by-step operational procedure | Numbered steps, commands, decision points |
| `postmortem` | Post-incident analysis | Timeline, root cause, action items |
| `sop` | Standard Operating Procedure for a recurring task | Checklist format with prerequisites |
| `incident-report` | Brief summary of an incident for stakeholders | Executive-friendly, no deep technical detail |
| `on-call-guide` | Reference for engineers paged at 2am | Symptom → action lookup format |

### Stage 1: Collect Incident or Procedure Information
Accept input in any form — stream of consciousness, bullet points, chat logs. Do not require structured input before drafting.

For a `runbook`, extract or ask for:
- What service/component is this for?
- What condition triggers this procedure?
- What is the expected end state?
- What permissions does the operator need?

For a `postmortem`, extract:
- When did the incident start and end?
- What was the user-visible impact?
- What was the timeline of key events?
- What was the root cause?
- What actions were taken to mitigate?
- What follow-up items exist?

For an `sop`, extract:
- How often is this task performed?
- What are the prerequisites?
- What are the failure modes and how to recover?

If critical information is missing, ask for it in one question. Draft from available information if the user says to proceed.

### Stage 2: Document Standards

**Runbook structure:**
```markdown
# Runbook: [Name]
**Service:** [name]
**Trigger:** [What condition prompts this runbook]
**Owner:** [Team or role]
**Last verified:** [Date]

## Prerequisites
- [Access/permission required]
- [Tools required]

## Symptoms
- [Observable signs that this runbook applies]

## Diagnosis
[Steps to confirm the issue before taking action]
1. `[command]` — [what to look for in output]

## Resolution Steps
1. [Action] — [why this step]
   ```bash
   [exact command]
   ```
   **Expected output:** [what success looks like]

2. [Next action]

## Verification
- [ ] [Check 1]
- [ ] [Check 2]

## Escalation
If the above steps do not resolve the issue within [N] minutes, escalate to [team/person] via [channel].

## Notes
[Known gotchas, version-specific behavior, related runbooks]
```

**Postmortem structure:**
```markdown
# Postmortem: [Incident title] — [Date]

## Summary
[2-3 sentence executive summary: what happened, what was impacted, duration]

## Impact
- **Duration:** [start] → [end] ([total minutes])
- **Affected services:** [list]
- **User impact:** [what users experienced]

## Timeline
| Time | Event |
|------|-------|
| HH:MM | [Event] |

## Root Cause
[Clear explanation of the technical root cause — not symptoms]

## Contributing Factors
- [Factor 1]
- [Factor 2]

## Resolution
[What was done to restore service]

## Action Items
| Item | Owner | Due |
|------|-------|-----|
| [Preventive action] | [Team] | [Date] |

## Lessons Learned
[What this incident revealed about the system or process]
```

### Stage 3: Quality Checks
Before presenting the output:
- Commands are in fenced code blocks, not inline
- Each step has an "Expected output" or verification indicator
- No step says "do the thing" without an exact command or decision tree
- Escalation path is specified
- Prerequisites are listed before steps

### Stage 4: Review Prompt
After presenting the draft, ask:
- "Are there any commands or steps I should add that you remember doing?"
- "Should I add a 'Known issues' section for common failure modes?"

## Done Criteria
- Document type is classified before drafting.
- Output follows the appropriate structure template.
- All commands are exact and in fenced code blocks.
- Every runbook has prerequisites, symptoms, resolution, verification, and escalation sections.
- Every postmortem has impact, timeline, root cause, and action items.
- No step requires the reader to already know what to do.