---

name: support-runbook description: "Write a support runbook for handling a recurring issue type consistently. Use when asked to write a support runbook, a troubleshooting playbook for agents, a handling guide for a common issue, or a tier-1 response procedure. Produces a runbook — issue identification, triage/severity, step-by-step diagnosis & resolution, decision tree, when/how to escalate, and the customer-comms templates — so any agent resolves it the same way."

Support Runbook Skill

When the same issue hits support repeatedly, every agent shouldn't reinvent the fix. A support runbook makes the resolution consistent and fast: how to recognise it, how urgent it is, the diagnostic steps, the decision tree, and exactly when to escalate (with what info). This skill writes that — turning tribal knowledge into a procedure tier-1 can follow.

Required Inputs

Ask for these only if they aren't already provided:

• The issue type — the recurring problem this runbook covers (e.g. "sync failures," "login loops," "billing discrepancy").
• How to recognise it — symptoms and how it's reported.
• The resolution path(s) — diagnostic steps and fixes (including the branches — "if X then…").
• Escalation — when it exceeds tier-1, who it goes to, and with what diagnostics.

Output Format

Support Runbook: [issue type]

1. Identify — the symptoms and how customers describe it (so agents recognise it from a vague ticket). What it's often confused with.

2. Severity / triage — how to rate urgency (is it down vs. degraded vs. cosmetic? affecting one user or many?) and the response-time expectation per level.

3. Diagnose — ordered steps to pinpoint the cause; what to check and what each result means. A decision tree where the path branches:

If [symptom A] → likely [cause] → go to Fix 1. If [symptom B] → check [thing] → if yes, Fix 2; if no, escalate.

4. Resolve — the fix per branch, step by step, including what to tell the customer to do (and what not to touch).

5. Escalate — the exact trigger to escalate (time-boxed: "if unresolved in N min" or "if it affects >X users"), who to (team/tier), and the diagnostics to attach so the next tier doesn't start cold.

6. Customer comms — ready snippets for the key moments: acknowledging, mid-resolution update, resolved, and "escalating, here's what's next" (pair with support-macro).

7. Prevention note — if this issue recurs a lot, the upstream fix/feature to flag to product/eng.

Quality Checks

• Identification covers how customers actually describe it (not just the internal name)
• Severity/triage guidance sets response expectations
• Diagnosis is a clear ordered path / decision tree, not a wall of tips
• Escalation has an explicit trigger, target, and the diagnostics to attach
• Customer-comms snippets cover acknowledge / update / resolve / escalate
• Flags the upstream fix if the issue is frequent (so support feeds product)

Anti-Patterns

• Do not write a tip list instead of an ordered path — agents need "do this, then this," with branches
• Do not leave escalation vague — "escalate if needed" means everyone escalates differently; time-box and specify the target + attachments
• Do not omit the customer comms — resolution + silence still feels like bad support
• Do not ignore severity — treating a full outage like a how-to question loses trust fast
• Do not let a high-frequency issue stay a runbook forever — flag the root-cause fix to product

Based On

Support-operations practice — issue triage, decision-tree diagnosis, time-boxed escalation, and consistent agent procedures.

Example Trigger Phrases

• "Write a support runbook."
• "Write a troubleshooting playbook for agents."
• "Write a handling guide for this common issue."
• "Write the tier-1 response procedure."