Support runbook & known-issue register

Use this to run a known-issue register: one place where every recurring or in-flight problem has a single confirmed answer, so any rep can recognise it, hand out the same tested workaround, and stop re-diagnosing something the team already understands. It is the support-desk version of what ITIL's problem-management practice calls a known-error database — a documented problem paired with a workaround.

The golden rule: one issue, one owner, one current answer. If two reps would tell the same customer two different things, the entry isn't finished.

Part 1 — The register (the index everyone scans first)

Keep this as one sortable table, pinned where the queue can see it. Reps check here before they escalate or improvise.

Status values, kept deliberately few:

Part 2 — The runbook entry (one per issue)

Copy this block for every issue in the register. Fill every [placeholder]; an empty field is a question a rep will have to ask you at 2am.

KI-[NN] — [short internal title]

• Status: [Investigating / Known issue / Fix in progress / Fixed – monitoring]
• Severity & scope: [who is affected, roughly how many, which plans/regions]
• First seen / last confirmed: [date] / [date]

How the customer describes it

[The exact phrasing customers use — paste a real quote. This is what reps match against.]

Confirm it's this issue (don't guess)

• [Diagnostic question to ask, e.g. "Which browser?"]
• [What to check in the tool / logs / admin panel]
• [The signature that separates this from a lookalike issue]

Do NOT

• [The plausible-but-wrong fix reps keep trying — e.g. "don't reset their password; it won't help and locks them out for 15 min"]

Workaround to give the customer

1. [Step]
2. [Step]
3. [Step, or "No workaround yet — see canned reply"]

Canned reply (copy-paste)

Thanks for flagging this — it's a known issue on our side: [plain-language cause].
In the meantime you can [workaround]. We're tracking a fix and I'll [update you /
you can follow our status page at [URL]].

Escalate when

• [Trigger, e.g. "customer is on [Enterprise] and fully blocked with no workaround"] → route per the escalation matrix to [team / on-call].

Tracking

• Engineering ticket: [link] · Status-page entry: [link] · Related KB: [link]

Owner & next review: [name] · [date]

Triage: is this already known?

Before anyone escalates or writes a fresh diagnosis, run this:

• Searched the register by symptom keyword — no match
• Checked open engineering tickets / the status page
• Asked in [the team channel] in case it's known but unlogged
• Reproduced it, or captured enough detail for someone who can

If all four come back clear, it's a new issue: add a register row at status Investigating, assign an owner, and treat everything above as the entry you're now filling in.

Keep it alive (or it becomes a lie)

A stale runbook is worse than none — reps trust it and hand out a workaround for a bug that shipped a fix a month ago. Guardrails:

• Every entry has a named owner and a next-review date. No owner, no entry.
• Review cadence: [weekly] for Investigating and Fix in progress, [monthly] for stable Known issues.
• When a fix ships: move to Fixed – monitoring, tell the reps who logged customers on it, and start a [X-day] clock before you retire it.
• When you retire an entry: pull it from the live index but keep the record — recurrence is common, and the old diagnosis saves the next investigation.
• One source of truth. If the workaround also lives in a macro or KB article, link those to this entry so a change propagates from one place.

Before you publish an entry

• A rep who's never seen it could recognise the issue from the "how the customer describes it" line
• The workaround has been tested, not assumed
• The canned reply is plain language — no internal codenames or ticket IDs
• Escalation trigger and destination are both named
• Owner and next-review date are set
• Linked to the engineering ticket so status stays honest