sop-creator

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: # [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 # 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 # 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 # 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: Is this for emergencies? → Runbook Is this a complex multi-phase project? → Playbook Is this a simple repeated task? → Standard SOP or Checklist Does it have lots of if/then branching? → Decision Tree Is it for debugging? → Troubleshooting Guide Is it recording a decision? → ADR Is it for someone new? → Onboarding Guide Metadata (Keep it Light) --- 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 Incidents, emergencies, on-call standard-sop.md Any repeatable process how-to-guide.md One-off tasks, setup onboarding-guide.md New person ramping up decision-tree.md Complex if/then flows 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