sop-creator

Original source / Raw SKILL.md

---
name: sop-creator
description: Create runbooks, playbooks, and technical documentation for engineering teams. Use when the user wants to document a process, create a runbook, build operational docs, or formalize any repeatable technical procedure. Triggers on requests like "create a runbook for...", "document this process", "write a playbook", or any technical documentation request.
---

# SOP & Runbook Creator

Create practical documentation that people actually follow.

## Philosophy

**Nobody reads 50-page docs.** Make it scannable, actionable, and impossible to misunderstand.

Core principles:
- **Scannable** - Headers, bullets, tables. No walls of text.
- **Actionable** - Every step is something you DO, not something you "consider"
- **Specific** - Numbers, names, thresholds. No "as needed" or "when appropriate"
- **Testable** - Clear success criteria. How do you know it worked?
- **Maintained** - Owner, last updated, review schedule

## SOP Categories

Pick the right format for your use case:

### Tech/Engineering
| Type | When to Use |
|------|-------------|
| **Runbook** | Emergency response, incidents, on-call |
| **Deployment Playbook** | Releases, migrations, maintenance |
| **Troubleshooting Guide** | Debugging, diagnosis trees |
| **How-To Guide** | One-off setup, configuration |
| **ADR** | Architecture decisions |

### Operations/Business
| Type | When to Use |
|------|-------------|
| **Process SOP** | Repeatable business workflows |
| **Checklist** | Quality control, verification |
| **Decision Tree** | Complex if/then scenarios |
| **Handoff Doc** | Role transitions, shift changes |

### Content/Creative
| Type | When to Use |
|------|-------------|
| **Production Workflow** | Content creation pipelines |
| **Review Process** | Approval workflows |
| **Publishing Checklist** | Pre-launch verification |

### General
| Type | When to Use |
|------|-------------|
| **Standard SOP** | Any repeatable process |
| **Quick Reference** | Condensed version of longer SOP |
| **Onboarding Guide** | New person ramping up |

## Universal Structure

Every SOP needs at minimum:

```markdown
# [What This Does]

> **TL;DR:** One sentence - what, when, who.

## Definition of Done

This is complete when:
- [ ] [Primary outcome]
- [ ] [Verification step]
- [ ] [Any handoff/notification]

## When to Use This
[Trigger conditions]

## Prerequisites
[What you need before starting]

## The Process
[Numbered steps - the actual work]

## Verify Completion
[Return to Definition of Done, confirm all checked]

## When Things Go Wrong
[Common issues and fixes]

## Questions?
[Who to contact]
```

**Definition of Done is the most important section.** Put it near the top. Make it a checklist. Be specific.

## Writing Rules

### Be Specific

| Don't Write | Write Instead |
|-------------|---------------|
| "Contact the team" | "Message @sarah in #ops-team" |
| "Wait until ready" | "Wait until status shows 'Complete' (~5 min)" |
| "Review carefully" | "Check items A, B, C in the dashboard" |
| "As appropriate" | "If value > 100" |
| "Regularly" | "Every Monday at 9am" |
| "Soon" | "Within 2 hours" |

### Action-First Steps

```markdown
# Bad
"The report should be reviewed before sending to ensure
accuracy and completeness of all data fields."

# Good
1. Open the report in [System]
2. Verify these fields are populated:
   - [ ] Customer name
   - [ ] Amount
   - [ ] Date
3. Click "Send"
```

### Warnings Come First

```markdown
# Bad
1. Delete the old records
   Note: This cannot be undone

# Good
> **WARNING:** This permanently deletes records. Export first if needed.

1. Delete the old records
```

### Decision Points are Clear

```markdown
# Bad
"Handle the request based on priority level"

# Good
**If priority is:**
- **Critical:** Drop everything, handle now, notify manager
- **High:** Handle within 4 hours
- **Normal:** Handle within 24 hours
- **Low:** Add to weekly batch
```

## Format Selection Guide

Ask yourself:

1. **Is this for emergencies?** → Runbook
2. **Is this a complex multi-phase project?** → Playbook
3. **Is this a simple repeated task?** → Standard SOP or Checklist
4. **Does it have lots of if/then branching?** → Decision Tree
5. **Is it for debugging?** → Troubleshooting Guide
6. **Is it recording a decision?** → ADR
7. **Is it for someone new?** → Onboarding Guide

## Metadata (Keep it Light)

```yaml
---
title: [Clear name]
owner: [Person or team]
last_updated: [Date]
review_schedule: [quarterly/annually/as-needed]
---
```

That's it. No document IDs, version matrices, or approval chains unless you actually need them.

## Templates

Each template is in `references/`:

| Template | Use For |
|----------|---------|
| [runbook.md](references/runbook.md) | Incidents, emergencies, on-call |
| [standard-sop.md](references/standard-sop.md) | Any repeatable process |
| [how-to-guide.md](references/how-to-guide.md) | One-off tasks, setup |
| [onboarding-guide.md](references/onboarding-guide.md) | New person ramping up |
| [decision-tree.md](references/decision-tree.md) | Complex if/then flows |
| [checklist.md](references/checklist.md) | QC, verification |

**All templates have Definition of Done as the primary success criteria.**

## Quality Checklist

Before publishing:
- [ ] Can someone unfamiliar follow this?
- [ ] Are all steps actionable (verbs, not descriptions)?
- [ ] Are specifics provided (names, numbers, thresholds)?
- [ ] Is there a clear "done" state?
- [ ] Is the owner/contact info current?
- [ ] Has it been tested recently?

## Anti-Patterns

**Kill these:**
- "Per company policy..." (just state what to do)
- "It is recommended that..." (just say "do X")
- "Please ensure..." (just say "check X")
- Passive voice ("the form should be submitted" → "submit the form")
- Describing what to do instead of showing it
- Walls of text with no structure
- Screenshots that will be outdated in a month

**Do these:**
- Start with the most common path
- Put edge cases at the bottom
- Link to related docs instead of duplicating
- Use tables for reference info
- Use checklists for verification steps
- Include "I'm stuck" escape hatches


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/runbook.md

```markdown
# Runbook Template

For: Incident response, on-call, emergency fixes.

```markdown
---
title: [Service] [Issue Type] Runbook
owner: [team-name]
oncall: "#[oncall-channel]"
last_tested: YYYY-MM-DD
---

# [Service] [Issue Type] Runbook

> **TL;DR:** [One sentence: what this fixes and when to use it]

## Definition of Done

You're done when ALL of these are true:
- [ ] [Primary success indicator - e.g., "Alert resolved"]
- [ ] [Secondary indicator - e.g., "Error rate < 0.1%"]
- [ ] [Verification step - e.g., "Health check returns 200"]
- [ ] [Cleanup step - e.g., "Incident ticket updated"]

## Symptoms

You're here because:
- [ ] Alert: `[alert-name]` firing
- [ ] [Error message or log pattern]
- [ ] [Dashboard showing X metric above/below Y]

## Quick Diagnosis

```bash
# Check service status
kubectl get pods -n [namespace] -l app=[service-name]

# Check logs
kubectl logs -n [namespace] deployment/[service-name] --tail=100 | grep -i error
```

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| [Symptom 1] | [Cause] | [Action] |
| [Symptom 2] | [Cause] | [Action] |

## Mitigation Steps

### 1. [First thing to try]

```bash
[command]
```

**Done when:** [How you know this step worked]

### 2. [Second thing to try]

```bash
[command]
```

**Done when:** [Completion criteria]

### 3. [If nothing else works]

```bash
[command]
```

**Done when:** [Completion criteria]

## Escalation

**Escalate if:**
- Quick fixes don't work after [X] minutes
- [Other escalation trigger]

**Contact:** [Person/channel] via [method]

## Post-Resolution

- [ ] Verify Definition of Done checklist above
- [ ] Update incident ticket with timeline
- [ ] Schedule postmortem if needed
```

```

### references/standard-sop.md

```markdown
# Standard SOP Template

For: Any repeatable process.

```markdown
---
title: [Process Name]
owner: [Person or team]
last_updated: YYYY-MM-DD
---

# [Process Name]

> **TL;DR:** [What this process does, in one sentence]

## Definition of Done

This process is complete when:
- [ ] [Primary outcome achieved]
- [ ] [Secondary outcome if applicable]
- [ ] [Verification/confirmation step]
- [ ] [Handoff/notification if needed]

## When to Use This

Use this when:
- [Trigger condition 1]
- [Trigger condition 2]

## Before You Start

- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]

## The Process

### Step 1: [Action]

1. [Specific action]
2. [Specific action]

**Done when:** [How you know this step is complete]

### Step 2: [Action]

1. [Specific action]
2. [Specific action]

**Done when:** [Completion criteria]

### Step 3: [Action]

1. [Specific action]
2. [Specific action]

**Done when:** [Completion criteria]

## Verify Completion

Go back to Definition of Done and confirm all items checked.

## Common Issues

| Problem | Solution |
|---------|----------|
| [Issue 1] | [Fix] |
| [Issue 2] | [Fix] |

## Questions?

Contact: [Person/channel]
```

```

### references/how-to-guide.md

```markdown
# How-To Guide Template

For: One-off tasks, setup, configuration.

```markdown
# How to [Do The Thing]

> **TL;DR:** [What this accomplishes in one sentence]

## Definition of Done

You're done when:
- [ ] [Primary success indicator]
- [ ] [Verification step]
- [ ] [Any cleanup/confirmation]

## Prerequisites

- [ ] [Access/tool needed]
- [ ] [Permission needed]

## Steps

### 1. [First Step]

```bash
[command or action]
```

**Done when:** [Expected result]

### 2. [Second Step]

```bash
[command or action]
```

**Done when:** [Expected result]

### 3. [Final Step]

```bash
[command or action]
```

**Done when:** [Expected result]

## Verify

Confirm Definition of Done:
```bash
[verification command or check]
```

Expected: [What you should see]

## Troubleshooting

**Problem:** [Common issue]
**Fix:** [Solution]

## Undo

If you need to revert:
```bash
[undo command]
```
```

```

### references/onboarding-guide.md

```markdown
# Onboarding Guide Template

For: Getting someone new up to speed.

```markdown
---
title: [Role/Project] Onboarding
owner: [Person or team]
last_updated: YYYY-MM-DD
---

# [Role/Project] Onboarding

> **Goal:** Get productive with [what] within [timeframe].

**Point of contact:** [Name, how to reach them]

## Definition of Done

Onboarding is complete when:
- [ ] All Day 1 access granted
- [ ] Week 1 learning completed
- [ ] First [task/project] completed independently
- [ ] Can answer: [key question they should know]

---

## Day 1

### Access
- [ ] [System 1] - [what it's for]
- [ ] [System 2] - [what it's for]
- [ ] [Communication channel]

### First Tasks
- [ ] [Orientation task 1]
- [ ] [Orientation task 2]
- [ ] Meet with [person]

**Day 1 done when:** All access working, met key people

---

## Week 1

### Learn
- [ ] [Document/resource 1]
- [ ] [Document/resource 2]

### Do
- [ ] [Hands-on task 1]
- [ ] [Hands-on task 2]

### Meet
| Who | Why |
|-----|-----|
| [Person 1] | [What you'll learn] |
| [Person 2] | [What you'll learn] |

**Week 1 done when:** Can explain [core concept], completed [task]

---

## Week 2-4

### Projects
| Project | Description | Help from |
|---------|-------------|-----------|
| [Project 1] | [What you'll do] | [Person] |

### Processes to Learn
- [ ] [Process 1] - [link]
- [ ] [Process 2] - [link]

**Onboarding done when:** Definition of Done checklist complete

---

## Resources

- **Docs:** [location]
- **Questions:** [where to ask]
- **Escalations:** [who to contact]

## FAQ

**Q: [Common question]**
A: [Answer]
```

```

### references/decision-tree.md

```markdown
# Decision Tree Template

For: Complex processes with conditional paths.

```markdown
---
title: [Decision Process Name]
owner: [Person or team]
last_updated: YYYY-MM-DD
---

# [Decision Process Name]

> **TL;DR:** How to handle [situation type]. Start at top, follow the path.

## Definition of Done

This process is complete when:
- [ ] Correct path identified and followed
- [ ] [Primary action completed]
- [ ] [Outcome verified]
- [ ] [Any notification/handoff done]

---

## Start Here

**What are you dealing with?**

| Situation | Go to |
|-----------|-------|
| [Situation A] | [Path A](#path-a) |
| [Situation B] | [Path B](#path-b) |
| [Situation C] | [Path C](#path-c) |
| Not sure | [Assessment](#assessment) |

---

## Assessment

**Question: [What to determine first]**

- If **[Answer A]** → Go to [Path A](#path-a)
- If **[Answer B]** → Go to [Path B](#path-b)
- If **unclear** → [Who to ask]

---

## Path A

**You're here because:** [Condition]

### Do this:

1. [Action]
2. [Action]
3. [Action]

**Done when:** [Completion criteria]

→ Go to [Verify Completion](#verify-completion)

---

## Path B

**You're here because:** [Condition]

### First, check [factor]:

| If | Then |
|----|------|
| [Condition 1] | [Action] |
| [Condition 2] | [Action] |
| None of above | Escalate to [contact] |

**Done when:** [Completion criteria]

→ Go to [Verify Completion](#verify-completion)

---

## Path C

**You're here because:** [Condition]

> **Warning:** [Important caution if applicable]

1. [Action]
2. [Action]
3. **Check:** [Verification point]
   - OK → [Next action]
   - NOT OK → Escalate to [contact]

**Done when:** [Completion criteria]

→ Go to [Verify Completion](#verify-completion)

---

## Verify Completion

Return to Definition of Done and confirm:
- [ ] Correct path identified and followed
- [ ] [Primary action completed]
- [ ] [Outcome verified]
- [ ] [Any notification/handoff done]

## Escalation

**Escalate if:**
- Stuck for more than [timeframe]
- [Other trigger]

**Contact:** [Person/channel]
```

```

### references/checklist.md

```markdown
# Checklist Template

For: Quality control, verification, recurring tasks.

```markdown
---
title: [Checklist Name]
owner: [Person or team]
last_updated: YYYY-MM-DD
---

# [Checklist Name]

> **Use when:** [Trigger for using this checklist]

**Date:** _______________
**Completed by:** _______________

---

## Definition of Done

This checklist is complete when:
- [ ] All required items checked
- [ ] Any failed items have follow-up logged
- [ ] Sign-off completed

---

## Section 1: [Category]

- [ ] [Item]
- [ ] [Item]
- [ ] [Item]

## Section 2: [Category]

- [ ] [Item]
- [ ] [Item]
- [ ] [Item]

> **If any items fail:** [What to do]

## Section 3: [Category]

- [ ] [Item]
- [ ] [Item]

---

## Sign-Off

**All items complete:** [ ] Yes  [ ] No

**Issues found:** _______________________

**Follow-up needed:** [ ] Yes  [ ] No

**Completed by:** _______ **Date:** _______
```

```