# Support Runbook > Generate a professional Support Runbook as a formatted Word (.docx) file — monitoring, logging, health checks, scheduled jobs, troubleshooting guide, routine operational checklist, and support process/escalation. Use this whenever someone asks for a "runbook," "support handbook," "on-call guide," "incident response doc," or wants day-to-day operational reference material for a support or on-call team (as distinct from how a system gets deployed, which lives in the companion operations-deployment-guide skill). Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, high-level-design, operations-deployment-guide, api-documentation, database-design, release-maintenance-guide) but fully usable standalone. - Skill: `vedkathe/support-runbook` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add vedkathe/support-runbook` - Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/support-runbook/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: VedKathe (https://skillmd.com/u/vedkathe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vedkathe/support-runbook --- # Support Runbook Generator Produce a single `.docx` document a support or on-call engineer reaches for during their shift — how to check system health, where the logs are, what to do when something breaks, and who to escalate to. Deployment and rollback procedures belong in the companion `operations-deployment-guide` skill — cross-reference it rather than duplicating. ## Sections (in this order) Cover page, Version History, Document Approval, Revision Log, and TOC are automatic — your `sections` array starts at "1. Monitoring". | # | Section | Content | Diagram? | |---|---|---|---| | 1 | Monitoring | Dashboards (tool, link, what they show), alert thresholds and severities, on-call rotation tool and escalation policy | **Monitoring Architecture** diagram | | 2 | Logging | Log sources, storage/retention, how to query, access control | | | 3 | Health Checks | Endpoints/mechanisms used, what "healthy" means, how failures are detected | | | 4 | Scheduled Jobs | Table: Job name, schedule/cron, purpose, owner, what happens on failure | | | 5 | Troubleshooting Guide | Table: Symptom, Likely Cause, Resolution — prefer real past incidents over hypotheticals if known | | | 6 | Operational Checklist | Routine tasks (dependency updates, access reviews, cert renewals) with owner and cadence | | | 7 | Support Process & SLAs | Support tiers, ticketing system, response-time SLAs | **Support Escalation Flow** diagram | | 8 | Escalation Contacts | Table: Role, Name/Rotation, Contact, When to Escalate | | | 9 | Appendix | Related runbook/deployment guide links | | ## Diagram Policy **Applies to the `.docx` path only** — Markdown embeds Mermaid source directly instead of rendering anything (see "Output Format" below). Prefer a real Mermaid diagram — rendered via `mmdc` and embedded with `B.diagramImage()` — over `diagramPlaceholder()`, but only once you have concrete structure to draw (real names, not "TBD"). Read `references/diagram-generation.md` when you're actually about to render one — it has the full build order, the bundled config (`assets/mermaid-config.json`), the exact `mmdc` flags, and token-saving tips. Skip it entirely if this document ends up needing no diagrams. ## Missing Information Policy Never invent alert thresholds, troubleshooting steps, or escalation paths you have no basis for — a fabricated "resolution" in a runbook could make an actual incident worse. Use `toBeCompleted("...")` for sections you lack real input for, explaining what's needed, and still generate everything else. ## Output Format Ask the user which output format they want, unless they've already said so in this request (e.g., "as a docx", "in markdown," "just give me an .md file") — a quick single-choice question is enough, don't block on it otherwise: - **Word document (.docx)** — the default assumption if the person hasn't specified and their context suggests a formal deliverable. Follow "Using the builder" below. - **Markdown (.md)** — no script needed, write the file directly. Use these conventions so it stays structurally equivalent to the docx version: - Front matter: instead of a cover page, open with the title as an `#` heading, the project name as an italic subtitle line, then a metadata table instead of separate Version History / Approval / Revision Log tables: ```markdown # Support Runbook *Acme Order Platform* | Field | Value | |---|---| | Version | 0.1 | | Author | Jane Doe | | Date | 2026-07-19 | | Status | Draft | | Approved By | Jane Doe (Tech Lead) | ``` - Headings: `#`/`##`/`###`/`####` matching the same section levels used in the table above — don't flatten everything to one level, that's what keeps the document skimmable and consistent with the docx version. - Tables: standard Markdown tables. - Diagrams — unlike the `.docx` path, don't render or embed an image here. Write the actual Mermaid source directly in a fenced code block; GitHub, GitLab, Obsidian, and most modern Markdown viewers render `mermaid` code blocks natively, so this is a real diagram, not a placeholder: ````markdown ```mermaid flowchart TD A[Client] --> B[API Gateway] B --> C[Order Service] C --> D[(Database)] ``` ```` Only fall back to a text placeholder if you don't yet have concrete enough detail to draw something real (mirrors `toBeCompleted` above): ```markdown > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED** > Not enough detail yet to draw the System Architecture Diagram — need > the actual component names and how they connect. ``` - "To be completed" callout — same blockquote treatment: ```markdown > ⚠️ **TO BE COMPLETED** > Explanation of what input is needed to fill this in. ``` - Save as `Support_Runbook.md` instead of `Support_Runbook.docx`. ## Workflow Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the `.docx` path. 1. Gather what's available — monitoring/alerting config, past incident history, on-call tooling — or ask directly. 2. Draft each section as data using the builder functions below. Prefer real past incidents for the Troubleshooting Guide over generic examples. 3. Build with `scripts/docx_builder.js`. 4. Skip PDF conversion by default — `docx_builder.js` is already tested and hardened (table widths and text alignment are enforced at the library level), so routine generations don't need a re-render just to confirm it worked. Only convert to PDF and view it if the user explicitly asks for visual verification, or if something about this generation is unusual (e.g., a new kind of content the library hasn't handled before, or a reported rendering problem). When you do need it: `soffice --headless --convert-to pdf .docx` (or `libreoffice --headless ...`), then `pdftoppm -jpeg -r 100 .pdf page` and view the images. 5. Save to `/mnt/user-data/outputs/Support_Runbook.docx` (or `.md` if that's the chosen format) and present it. ## Using the builder (for the .docx path) This library requires the `docx` npm package. Before running any script, check it's available with `node -e "require('docx')"`; if that fails, install it with `npm install docx` in the working directory first — don't assume it's pre-installed, since that varies by environment. ```javascript const B = require("./scripts/docx_builder.js"); const sections = [ B.h1("1. Monitoring"), B.para("Dashboards are hosted in Grafana; PagerDuty manages on-call rotation and escalation."), // Prefer B.diagramImage(path, {caption}) with a real mmdc render when // possible (see "Diagram Policy" above) — diagramPlaceholder() is the fallback: B.diagramPlaceholder({ name: "Monitoring Architecture", purpose: "Show how metrics flow from services to dashboards and alerts.", recommendedContent: ["Services", "Prometheus", "Grafana", "PagerDuty", "Slack"], }), B.h1("5. Troubleshooting Guide"), B.table(["Symptom", "Likely Cause", "Resolution"], [["Service returns 503", "Downstream dependency down", "Check dependency health dashboard; if down, page the owning team"]], [3000, 3000, 3200]), B.h1("8. Escalation Contacts"), B.toBeCompleted("On-call rotation and escalation contacts weren't provided — ask for the PagerDuty schedule link or current on-call roster."), ]; await B.buildDocument("/mnt/user-data/outputs/Support_Runbook.docx", { docLabel: "Support Runbook", title: "Support Runbook", subtitle: "Acme Order Platform", versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]], approvers: [["Jane Doe", "Support Lead", "", ""]], revisionLog: [], sections, }); ``` Available functions: `h1`/`h2`/`h3`/`h4`, `para`, `bullets`, `table(headers, rows, widths)`, `pageBreak`, `toBeCompleted(explanation)`, `diagramPlaceholder({name, purpose, recommendedContent, notes})`, and `buildDocument(path, options)`. Always use heading functions for titles so Word's Table of Contents and Navigation Pane work correctly. ## Success Criteria A support or on-call engineer who has never seen this system before should be able to triage a real incident using only this document — check health, find the right logs, recognize a known symptom, and know who to escalate to.