Runbook WriterCAUTION

1255 professional Agent Skills for Claude, ChatGPT, Gemini, Cursor & Codex — PRDs, postmortems, leases, medical bills, layoffs, go-bags, new countries. Plain markdown, MIT, in Anthropic's plugin directory. Plus a typed decision layer: which skill, is it safe, ship or slip. Free in-browser or npx pm-

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: runbook-writer
description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths."
---

# Runbook Writer Skill

Produces operational runbooks for services, incident types, and deployment procedures — structured so an on-call engineer who's never touched the system can follow them under pressure.

## Required Inputs

Ask for these if not provided:
- **What the runbook is for** (e.g. deploying the payment service, responding to a database failover, rotating API keys)
- **Runbook type** (Deployment / Incident Response / Maintenance / Disaster Recovery)
- **System/service name and what it does** (brief description)
- **Audience** (new on-call engineers / experienced SREs / DevOps team)
- **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js)
- **Monitoring tools** (e.g. Grafana, Datadog, CloudWatch, Splunk — used to name specific dashboards and alert links in the steps)
- **Key environment details** (e.g. Kubernetes cluster name, AWS account/region, relevant namespaces or resource names — paste what's relevant for exact commands)

## Output Format

---
**Runbook:** [Runbook Title]
**Service:** [Service Name]
**Type:** [Deployment / Incident Response / Maintenance / DR]
**Last Updated:** [Insert today's date in YYYY-MM-DD format]
**Owner:** [Team or person]
**Severity:** [P1 / P2 / P3 — if incident-type]

---

### Overview
**What this runbook covers:**
[1–2 sentences on the scenario this runbook handles]

**When to use this runbook:**
- [Specific trigger condition 1 — e.g. PagerDuty alert: `high-error-rate-payment-service`]
- [Specific trigger condition 2 — e.g. Deploy needed after PR merged to `main`]

**Estimated time to complete:** [X minutes / X–Y minutes depending on outcome]

**Impact if not completed correctly:** [e.g. Payment processing degraded / Data loss risk / Users locked out]

---

### Prerequisites

**Access required:**
- [ ] [System/tool access — e.g. AWS Console: `production-account`]
- [ ] [Credential — e.g. `vault read secret/payment-service`]
- [ ] [VPN / bastion access if needed]

**Tools required:**
- [ ] [Tool name and version — e.g. `kubectl` v1.28+]
- [ ] [CLI or dashboard name]

**Before you start:**
- [ ] [Prerequisite check — e.g. Verify current deployment is healthy in Grafana]
- [ ] [Prerequisite action — e.g. Announce in `#ops-live` that you're starting]

---

### Procedure

Number every step. Use exact commands. Do not paraphrase tool names or flags.

**Step 1: [Action name]**
[What you're doing and why — one sentence]
```bash
# Exact command
[command here]
```
**Expected output:** `[what should appear if this worked]`
**If this fails:** [Exact error message to look for] → [What to do, or see Troubleshooting]

**Step 2: [Action name]**
[Same structure as Step 1]

**Step 3: Verify**
Always include a verification step after the main procedure:
```bash
[verification command]
```
**Expected state:** [What a healthy system looks like after this runbook completes]

---

### Rollback

How to undo this procedure if something went wrong:

**Step R1: [Rollback action]**
```bash
[rollback command]
```
**Verify rollback:** `[command to confirm rollback succeeded]`

---

### Troubleshooting

| Symptom | Likely Cause | Resolution |
|---|---|---|
| [Error message or observable symptom] | [Why this happens] | [Exact fix or next step] |
| [Another symptom] | [Cause] | [Resolution] |

---

### Escalation

If this runbook does not resolve the issue:

| Condition | Who to Contact | How |
|---|---|---|
| [e.g. DB unavailable after 10 min] | [DBA on-call] | [PagerDuty policy: `db-oncall`] |
| [e.g. Payment provider unresponsive] | [Vendor contact] | [Contact in 1Password: `vendor-escalation`] |

**Always update the incident timeline in [tool] before escalating.**

---

### Post-Procedure Checklist

After completing the runbook:
- [ ] Announce completion in `#ops-live` with outcome
- [ ] Update the incident ticket / deploy log
- [ ] Verify alerts have resolved in monitoring dashboard
- [ ] If this revealed a gap in this runbook — update it now (link to edit process)

---

## Deeper Materials

This skill ships with support files — use them when they are available:

- **`references/3am-usability.md`** — The 3AM Test: Runbooks for Degraded Humans. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
- **`templates/runbook.md`** — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

## Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

| Dimension | 0 | 5 | 10 |
|---|---|---|---|
| **Command exactness** | Steps are vague actions ("run the deploy script") with no commands | Most steps have commands, but some paraphrase tool names or omit flags | Every step has an exact, copy-pasteable command with correct flags and placeholders clearly marked |
| **Success & failure signalling** | No expected outputs; reader cannot tell whether a step worked | Expected output on the happy path only; failure paths say "investigate" | Every step states expected output and a named failure path or troubleshooting link |
| **Rollback completeness** | Rollback missing or left as a placeholder | Rollback commands exist but are partial and have no verification | Rollback is complete, independently testable, and each rollback step has its own verify command |
| **Cold-reader usability** | Assumes system knowledge; unexplained jargon; escalation cells like "[Team name]" | Followable by a team member, but tribal-knowledge gaps would stall an outsider | An engineer who has never to

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

templates/pm-discovery-agent/skills/assumption-mapper/SKILL.md

templates/pm-discovery-agent/skills/discovery-interview-guide/SKILL.md

templates/pm-discovery-agent/skills/job-story-mapper/SKILL.md

templates/pm-discovery-agent/skills/user-interview-synthesis/SKILL.md

templates/pm-launch-agent/skills/content-calendar/SKILL.md

Gates applied: no_behavioural_pass.