Problems & Knowledge

Scope

Problem management is how a desk stops fighting the same fire monthly. This guide keeps the problem and knowledge workflows and removes private implementation detail.

This is the operator how-to for the problem-management and knowledge workflows: turning recurring incidents into a root-cause investigation (RCA), building the before they reach an agent. Problem work lives in the Problems workspace (the relevant workflow, L2/ops); knowledge lives in the Knowledge workspace (the relevant workflow); and both surface as deflection panels on the agent desk (the relevant workflow).

Both workspace headers carry the workspace switcher; arriving from a persona shell (the L2 Operations cards, or a Desk ⌘K command) adds a ← Back to L2 Operations (or Service Desk) return to the exact origin. Selecting a problem or article shows a breadcrumb (Problems → PRB-xxxx, Knowledge Base → title) above the detail header.

Both workspaces are fully shareable: the selected problem/article and, for Problems, the active tab all live in the URL (?problem=<id>, ?tab=kedb, ?article=<id>). Copy the address bar to hand a colleague the exact record and view you’re looking at — reloading lands back in the same place.

Problems: from symptom to root cause

A problem tracks the root cause behind one or more incidents. It moves through a dedicated RCA state machine:

with rework (pending_review → rca_draft) and dismissal (→ closed) paths.

Intake

Problems arrive three ways:

• From an incident — on a resolved/closed incident, raise a problem to explain it; the incident is linked automatically (caused_by).

• Auto-detected — Beacon’s hourly pattern sweep clusters recent incidents by category and, when five or more in a 7-day window aren’t already covered by an open problem, opens a candidate problem in the detected queue with every incident pre-linked. This is deterministic (category + count, no AI) and exists to prompt a human, not to auto-remediate.

• Manually — create one directly in the Problems workspace (needs problems.manage). The Link incident field is a search picker: type a ticket number (INC-000048), just its digits (48), or a few words of the title, then pick the incident from the list. You never need an internal id.

Work the detected queue: open an RCA on the ones worth investigating, dismiss the noise.

Root-cause analysis

• Start root-cause analysis moves detected → rca_draft.

• Fill in the RCA content: root-cause summary and two workaround fields (KNB-13). The internal workaround (agents only) is your runbook — hostnames, service names, “do NOT restart X” cautions are all fine; it is only ever shown to operators. The customer-safe summary is what a requester sees once the known error is published — write it for the affected user, in their terms. Leave the customer-safe field empty and requesters simply never see this known error in portal deflection (that is the safe default, not an error). Edit these on the problem detail pane at any time before closure.

• Beyond the free-text summary, the detail pane’s structured root-cause analysis card lets you build the investigation out of three optional sections — an incident timeline, a five-whys chain (why / because pairs), and contributing factors (factor, category, detail) — kept as the durable record of how the cause was found, for the next person who reopens this problem’s history. (The API attaches these sections to a KEDB match result too, but neither the desk’s KEDB panel nor the Problems workspace’s KEDB tab renders them today — an agent deflecting off a known error currently sees only its summary and workaround, not the five-whys behind it.) The change’s “Raised from problem” card (below) also stays to the free-text RCA summary and known-error flag.

• Submit for review moves rca_draft → pending_review. A non-empty root-cause summary is required — Beacon blocks the submit without one.

• A reviewer approves (→ approved) or sends it back with amend (→ rca_draft). A problem that turns out to be a dead end can be rejected (dismissed to closed).

• Attach more evidence as it surfaces via the Linked incidents card: search by incident number, digits, or title in the picker and hit Link incident. Already-linked incidents are greyed out in the results; unlink with the unlink icon next to each row. Only incidents can be linked — picking is restricted to incidents, and the API refuses anything else with a clear error.

Who signs off — the Accountable group

Raising a problem and drafting its RCA is open to anyone with problems.manage (RACI: Responsible). Approving it is not, once a tenant names an Accountable group — typically L3/Engineering, since root causes are usually design issues or SOP gaps. With a group set, Approve, Verify, and Close (including rejecting/abandoning) all require membership in it; submitting for review and pulling a submission back to draft stay open to whoever is doing the work.

• Each problem shows its own accountable-group badge (A: <group>) on the detail header — click it (needs problems.manage) to route this problem to a different domain group. The Problems workspace header itself carries a second control — the accountable-group button next to New problem (visible to problems.manage holders) — that sets the tenant-wide default new problems inherit (GET/PUT /problems/practice-settings); a problem with no group of its own falls back to that default, and with neither set the gate is off and any problems.manage holder can approve.

• Layered on top of the RACI gate: nobody approves an RCA they authored (segregation of duties). Authorship is read from who edited the RCA content or submitted it for review, plus the problem’s own requester — not from a role, so it cannot be routed around by changing who is in the group. A

Fix and verify

From an approved problem you can raise a linked change directly from the RCA (needs both problems.manage and changes.author). Beacon seeds the change from the RCA (title Fix: {problem}, description referencing the problem and its summary) and links them both ways. When that change enters implementation the problem advances to implementing on its own. Verify the fix

The Raise-change dialog also takes a proposed start (and optional end). For a normal change this matters: change governance will not let the CAB approve it until it has a start far enough out, so the dialog warns you when you leave it empty. You can also set it later on the change itself — its Set window action works while the change is still draft or submitted.

If the CAB rejects the corrective change, the problem does not get stuck at change_created: it returns to approved, where you can raise a different remediation. Re-submitting the rejected change after rework puts the problem back on the remediation track automatically. If nobody will pursue a second attempt, Close the problem straight from change_created.

On the change side, a change raised this way shows a Raised from problem card carrying the problem’s number, status, known-error flag and root-cause summary, so a CAB member approving it can see what it is fixing without leaving the change. The reverse link works too: the problem’s header shows the linked change as a clickable badge (→ CHG-000123) that opens the change directly.

Cost of a problem

The detail pane’s Cost of this problem card answers “what is this actually costing us” — it rolls up recorded time-tracking effort across the problem itself and every linked incident: investigation minutes, incident minutes, total effort, and a linked-incident count next to how many of those incidents actually have time recorded, so an under-recorded set reads as under-recorded rather than as cheap.

Money is shown only when the tenant has configured a labour rate — the same header settings dialog as the Accountable-group control, below a divider, holds the rate-per-hour and currency-code fields (admin.settings.manage to change; anyone with problems.view can see what is or isn’t set). With no rate set, the card says so and shows effort only, rather than printing a fabricated figure or a silent zero.

Known-Error Database (KEDB)

A known error is published, not checkbox-flagged (PRB-1). Once a problem’s RCA has cleared review (status at least Approved), Publish known error in the RCA card serves its workaround from the KEDB; Retire known error pulls it back. Publishing needs an internal workaround (there is nothing to serve without one) but not a customer-safe summary — a desk-only known error is legitimate; it just stays invisible to requesters until you author portal text. The KEDB serves only published, un-retired records. When the problem is verified or closed, the known error retires automatically — the root cause is fixed, so the workaround is no longer the right guidance. Every publish/retire is on the audit trail.

• Browse/search: the Problems workspace’s KEDB tab (?tab=kedb, needs problems.view) opens on the known-error register — every record, newest first, retired ones labelled Retired — and the search box ranks known errors by relevance over their title, root-cause summary, and workaround. Matching is lenient (any overlapping symptom term hits), so partial descriptions still find the right entry.

• On the desk: the KEDB suggestions panel on an open incident has two halves. The top half is automatic — it surfaces known errors matching the incident’s title and description as soon as the panel opens. Below it is a lookup box the agent can type into directly. Both need the narrow problems.kedb.view permission (or problems.view) — a read scoped to known-error search alone: it does not open investigations, RCA drafts, or the rest of the problem practice, so a first-line role can hold it without gaining problems.view. The Related tab’s badge shows the match count (with a “· KE” marker) the moment the ticket opens, so you know a workaround exists without switching tabs.

• At requester intake (KNB-1, KNB-13): while a requester types their report, the portal shows matching published known errors as a “known issue IT is already working on” panel — title and the customer-safe summary only. The internal workaround, like the RCA, never reaches a requester: publishing consents the record, authoring the customer-safe summary consents the text, and a published known error without portal text simply does not appear in the panel. When the problem closes, the same customer-safe summary (never the internal one) is what each linked incident’s requester is told.

Keep both workaround fields current: a stale workaround is worse than none, because agents — and requesters — trust the panel.

Knowledge base

The Knowledge workspace is where you author and publish articles for both agents and requesters.

Authoring

Create an article (needs knowledge.author), write the summary and body, and it starts as a draft. Articles are versioned — each edit is a new version you can review.

Who can read this? (audience)

Every article has an audience, set on the create form and on the edit pane:

Audience	Who sees it
Internal — agents only (default)	Only people with knowledge-base access. Requesters never see it, at any lifecycle stage.
Requester portal	Once published, anyone in the requester portal can search, read, and be offered it at intake.

Audience and lifecycle are two separate decisions, and this is the part worth getting right:

• Publishing does not make an article public. Publishing an internal article makes it live for agents. Putting it in front of end users takes the explicit Requester portal choice as well.

• Every article is internal by default, including every article that existed before this feature shipped. Nothing was retroactively exposed.

• The library list and article header both show an Internal / Portal badge, so you can see at a glance what a page is reaching.

• Widening the audience must be confirmed before it happens. Saving an edit that moves an article from Internal to Requester portal opens a type-to-confirm dialog first — you type — and the dialog states the consequence: for a published article, every requester can read the full text immediately and there is no undo for what they may already have read; for an unpublished one, it becomes requester-readable the moment it is published. One confirmation covers the whole save, including any title, body, or summary edits made in the same edit session. After the save, the toast states the real exposure (“now live in the requester portal” when the article is already published), and the change is audited. Narrowing back to Internal never asks for confirmation — removing requester access is the safe direction.

• Narrowing an article back to Internal — or unpublishing it — removes requester access immediately.

Before you set an article to Requester portal, read it once as an end user would: internal hostnames, admin steps, ticket numbers, and named staff do not belong in portal-facing knowledge.

Publish flow

1. Draft it (knowledge.author).
2. Choose the audience — Internal, or Requester portal.
3. Publish (knowledge.publish) to make it live for that audience.
4. Retire (Archive) it when it goes stale; Restore brings it back as a draft.

Promote an incident to KB

The fastest way to grow the knowledge base is to capture a real resolution. On a resolved or closed incident on the desk, use Promote to KB (needs incidents.promote_kb) to spin up a draft article seeded from that incident. Tidy it up and publish. Promoting takes you straight to the new draft in the Knowledge workspace (the relevant workflow) — not the bare library index — so the next step is right there.

Two guardrails and a prompt (KNB-1):

• Promotion requires the incident to be resolved/closed **with resolution resolution content is not knowledge.

• When a resolved incident has real resolution notes and no article captured from it, the desk’s Next: line prompts “Capture this resolution as knowledge” — one click runs the same Promote-to-KB action.

• Reporting counts what slipped through: Resolutions without knowledge capture on the summary report lists the window’s resolved incidents the KB never learned from. Work the list down; see

Deep-linking an article

Every article is addressable at the relevant workflow: reload, bookmark, or share that URL and the Knowledge workspace opens straight to it. This is what makes the two links below actually useful.

Deflection

Published articles do real work in three places:

• Agent desk — the KB suggestions panel surfaces relevant articles on the open ticket so the agent can answer with a known-good response instead of writing one from scratch. Each suggestion links straight to that article (the relevant workflow), not the bare library — no re-searching for the article the panel already found. This spans both audiences: an internal runbook is often exactly what the agent needs.

• Requester portal → Help articles — a dedicated browse-and-search tab over your portal-visible articles. Portal-audience articles only.

• Requester intake — while a requester types their issue, the portal searches your portal-visible articles and offers up to three matches inline. If one solves it, they close out and no ticket is filed.

Is it actually working?

Both intake outcomes are recorded — “this solved it” and “showed them an article, they filed anyway”. They surface as the self_service_deflection_rate metric on the XLA scorecard (the relevant workflow), and the metric’s evidence drill-through lists the tickets people filed despite being handed an article. That list is the work queue: those are the articles that aren’t answering the question they rank for. The metric is suppressed below five decisions rather than reporting a number nobody should trust.

Quick reference — who can do what

Action	Permission
View problems, the KEDB tab, and the cost/RACI settings	problems.view
Create, RCA, transition, link incidents	problems.manage
Look up the KEDB from the desk’s lookup box only (no problem records)	problems.kedb.view
Raise a change from an RCA	problems.manage + changes.author
Route a problem’s accountable group / set the tenant default	problems.manage
Set or clear the tenant labour rate	admin.settings.manage
Read the internal knowledge library	knowledge.view
Read portal help articles (requesters)	knowledge.portal.view
Author / edit articles, set the audience	knowledge.author
Publish / retire articles	knowledge.publish
Promote an incident to KB	incidents.promote_kb