--- name: runbook-authoring description: "Use when turning an alert, symptom, or piece of on-call tribal knowledge into a repeatable operational runbook that a stranger can execute at 3am. Writes an imperative, copy-pasteable procedure — trigger, preconditions, numbered command steps, decision branches, rollback, a verify-resolved gate, and an escalation trigger. Do NOT use for a blameless postmortem, a customer-facing status-page update, or classifying an incident's severity." metadata: decimalai-skill-id: "b97c1885-5f29-4918-832f-7ad3b878d2d9" decimalai-version-id: "61fa4f9c-5bd3-4b84-89bc-e7df30d9a277" decimalai-version: "1" decimalai-body-sha256: "cfbbaedd1f6d1aa8afa6b6697c29d3669e542984a6986dc518cda3dd01d3b8c2" decimalai-name: "runbook-authoring" decimalai-format: "1" decimalai-invocation: "model" decimalai-category: "devops" decimalai-source: "https://app.decimal.ai/s/runbook-authoring@1/SKILL.md" --- # Operational Runbook Authoring A runbook is not a troubleshooting essay. It is a procedure the tiredest, least-context engineer on the team can run at 3am and reach a known-good state without waking anyone. Base models default to prose troubleshooting — "you could check the logs, and it might be a connection issue, so consider restarting the service." That reads fine and helps no one under pressure. A runbook replaces *might* and *consider* with **run this, read that number, and if it exceeds N do this**. Write every runbook as an ordered, imperative, copy-pasteable procedure. The reader should execute top to bottom, copying commands verbatim, and only make a decision where you explicitly hand them one with a concrete threshold. ## The skeleton (always in this order) 1. **Trigger** — the exact alert, symptom, or condition that means "run this runbook." Name the alert, the paging text, or the observable symptom. One line. 2. **Preconditions** — the access, tools, and context required *before* step 1: which cluster/account, what credentials or role, which dashboard open, any safety check ("confirm you are on prod, not staging"). If a precondition is missing the reader stops here, not three steps in. 3. **Diagnosis + remediation steps** — numbered. Each step is an imperative sentence and, where an action is taken, an exact command in a fenced block. Commands use `` placeholders for values the reader fills in. Every command that reads state is followed by *what number to look at and what it means*. 4. **Decision branches** — wherever the path forks, state the concrete condition, not a vibe. "If p99 latency is above 2s **and** rising, go to step 6; otherwise go to step 9." Never "if it seems bad." 5. **Rollback** — the explicit revert. What single action returns the system to the last known-good state (revert the deploy, restore the config, scale back), and how to confirm the rollback itself took effect. 6. **Verify resolved** — a hard gate, not an afterthought. The exact command(s) and the specific values that prove the incident is over (error rate back under X%, queue depth draining, health check green for N minutes). The reader does not close the incident until this passes. 7. **Escalation trigger** — the precise condition under which the on-call stops and pages someone else: "If after step 8 the error rate is still above 5% after 15 minutes, page the @database-oncall." Name the team/rotation and the time-or-metric bound. ## Rules that make it copy-pasteable - **Imperative voice only.** "Run", "Check", "Restart", "Roll back" — never "you might want to" or "it could help to". The reader is executing, not deliberating. - **Exact commands in fenced blocks**, with placeholders in `` for environment-specific values. No pseudo-commands, no "check the logs" without the command that shows them. - **Every read has a meaning.** After a command that prints a number or status, say what reading is normal and what reading means trouble. A command with no interpretation is noise at 3am. - **Branches carry thresholds.** Every "if" has a number, a state, or a boolean the reader can evaluate without judgment. Move a judgment call up into an explicit branch or send it to escalation. - **Rollback is always present**, even if it is "no rollback needed — this is read-only." Say it, don't omit it. The reader must never have to guess whether undo is possible. - **Verify-resolved and escalation are both mandatory sections.** A runbook with no finish line and no give-up line is a way to stay stuck forever. - **No blame, no narrative.** A runbook is not a postmortem and not a status update. It does not explain what went wrong last time or reassure a customer — it tells the on-call what to do now. ## Template ```markdown # Runbook: **Trigger:** **Preconditions:** - Access to - and confirm you are on **prod** - open in another tab ## Steps 1. . Run: ``` > ``` Normal: . If instead, the issue is — go to step 3. 2. . Run: ``` ``` 3. **Branch — :** If is above , go to step 4. Otherwise go to step 6. ... ## Rollback : ``` ``` Confirm rollback: should show . ## Verify resolved Run: ``` ``` Resolved when: . Do not close the incident until this passes. ## Escalation If still holds after