Problems & Knowledge

Scope

How to open and work a problem, record known errors, and write knowledge articles.

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.

Knowledge articles support Markdown for readable procedures. Beacon renders the reader view without raw HTML, strips unsafe links, and does not load article images; an omitted image is shown as its alt-text note. Put required steps in text, not in an image. Markdown formatting and GFM tables or task lists remain readable for both operators and requesters within the article audience.

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. The picker shows only incidents currently inside your Problem-management tenant, organization, queue, and audience scope; it does not require the separate generic ticket-browsing permission.

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

New Problem keeps your unsent work as a draft; reopening offers Resume or Discard. Before submitting, Beacon saves a recovery reference for that exact request. If browser storage cannot save it, your inputs remain available and sending is blocked. If the response is lost, open Pending Problem creations and choose Check current Problem. No visible record yet does not prove creation failed; Retry this same saved request safely reuses its original request key and body.

After reload, Resume saved request restores the saved fields without sending. A returned current Problem is shown before you acknowledge it or open it. Deleted records are not recreated by retry. If you need to investigate a separate issue, Keep pending and start a separate Problem explains the consequence and retains the earlier request in the pending list. This is a distinct new Problem, not a retry. Do not remove browser recovery data merely to recover a lost response.

The optional incident picker requires tickets.view; Problem creation itself requires problems.manage.

Root-cause analysis

• Start root-cause analysis moves detected → rca_draft. You can keep typing while it completes: a successful start preserves your text for the next save. If starting fails, your draft stays available with the recovery message.

• Fill in the RCA content: root-cause summary and two workaround fields. 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 resolves the selected number again when linking so a result that became inaccessible cannot be attached.

Correct reviewed root-cause evidence

Reviewed RCA fields are read-only. Choose Correct reviewed RCA, explain the new evidence, and confirm the consequence: the prior approval becomes history, published known-error guidance is retired, and the correction needs fresh independent review. A linked corrective Change keeps its own lifecycle and controls. The Problem shows its recorded remediation phase separately while review is outstanding. A previously verified Problem needs fresh verification; the old verification is not silently carried forward.

Save the corrected summary and structured evidence, then submit for review. The reviewer checks the displayed evidence under the current accountable-group and authorship rules. After approval, the Problem resumes the current corrective work phase. Publish the reviewed workaround again only when it is appropriate; publication does not happen automatically.

If a save or decision fails or its outcome is uncertain, keep the retained draft and choose Read current Problem. Compare the current recorded evidence with your retained input, then explicitly confirm that review before another action. Reading a current record does not prove that the uncertain request produced it. The interface preserves your original captured evidence until you make that choice; it never silently approves or saves a replacement version.

You may abandon a correction with a reason instead of being forced to approve unwanted work. A live corrective Change must be completed through Change management, or eligible unshipped work may be explicitly abandoned with its own transition permission and reason. Approved, scheduled and implementing Changes cannot be stopped from this Problem action. Abandonment preserves the evidence history, makes no claim that the cause was verified, and sends no unreviewed workaround to linked requesters.

Open RCA and review history on the Problem to inspect recorded actors, local time with UTC/zone context, review and correction events, and older pages. Expand View captured evidence to read the exact RCA, internal workaround, public workaround and structured evidence saved with that event. Older events may say that no evidence snapshot was captured; Beacon does not reconstruct an old approval from the current RCA. A failed history read offers Retry and does not mean there is no history. The history is internal Problem work and remains subject to your current Problem viewing scope.

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.

Recover an unconfirmed corrective change

If raising a corrective change is not confirmed, keep the dialog open: the remediation plan, backout plan and proposed window remain available. Select Read current problem. Beacon shows the current status and linked change without attributing that record to the earlier attempt. A failed read remains retryable; an empty link is only an observation, not proof that creation failed.

Select Show the current problem to return to its actual record and follow its linked change. If the current problem is still approved, Review complete; allow an explicit retry enables another deliberate attempt. Beacon locks the problem and rechecks its current status and existing corrective change before creating work. Nothing is submitted automatically. Busy operations prevent duplicate submission and dismissal; closing and reopening after an uncertain outcome still requires a current read.

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. 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: 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.

Settings controls wait for the current save before accepting another save or closing the dialog. If a save cannot be confirmed, your selected group or typed rate/pattern values remain visible with an error. Retry the selected group explicitly, or use the existing save action for the retained inputs. A network error alone does not establish whether the server committed the setting.

Source: ProblemWorkspace.tsx settings write guards; no API contract changes.

Recover settings and known-error reads

If Problem practice settings cannot read the accountable group, labour rate or pattern parameters, use the Retry beside that failed dependency. You stay on the same page and retain rate, currency and pattern inputs already typed. Group choices require permission to view groups; a failed read is not an empty list or an unset policy.

The known-error register is paged, including labelled retired entries. Its Retry reloads the current page. Search keeps your query in the URL and offers explicit Search and Retry actions; stale responses from a prior query are discarded. Search shows up to 20 ranked matches, not a complete total. Clear the query with Browse all known-error records to return to the paged register.

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.

In Edit, search the Category picker to choose an association, or choose No category to remove it explicitly. Category choices need permission to view ticket categories. Loading or failed reads keep the recorded association; use Retry after a read error. Recorded category unavailable means the current category could not be found in the available choices, not that it has been removed. Your text and category choice remain after a failed save, and Cancel restores the recorded category. Saving a changed category supersedes a pending publication review and returns a published article to draft for publication again.

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.

Publishing many articles at once

Importing or seeding a library lands everything as drafts, and clicking Publish on three hundred articles one at a time is not a workflow. If you hold knowledge.publish, the article list in the relevant workflow carries a checkbox on every row and a select every article on this page box above them. Tick what you want and the four lifecycle verbs — Publish, Unpublish, Archive, Restore to draft — appear, applying to the whole selection at once.

Things worth knowing before you use it:

• It is the same verb, not a shortcut past the rules. Every article goes through the same lifecycle checks as the single-article button, so a bulk run can never put an article somewhere you could not have put it by hand. An archived article, for instance, still has to be restored to draft before it can be published.

• Selection covers the page you can see. Turning the page, switching the Published/Drafts/Archived tab, or typing a search clears the selection, so a bulk action can never reach a row that has scrolled out of sight.

• Publishing widens who can read. An article set to the Requester portal audience becomes visible to requesters the moment it publishes — check the audience badges on the rows before you publish a batch.

• You are told exactly what happened. The confirmation names the count (and asks you to type it for more than ten rows), and the result says how many changed, how many were already there, and how many were refused — with a message per refused article explaining why. A batch is never reported as a flat success.

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:

• 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

Verify that recurrence fell

The Problem record’s Observed recurrence card shows the frozen category and scope, detection count, equal before/follow-up windows, and when observation is complete. Use Read incidents to page through the exact members visible in your current scope. After the corrective Change has a successful explicit implementation result, its required reviews are complete, and the follow-up window ends, choose Verify observed decrease.

Beacon will not treat an older integration’s missing implementation result as success. An ordinary Change can retain Implementation outcome was not recorded for compatibility, while a Change bound to this measured recurrence must record Successful, Failed, or Rolled back before leaving implementation.

If an incident source was deleted, its row says that the recorded incident is no longer available. Beacon does not show its number, time, title, or former scope. A missing row can also mean it is outside your current access scope.

Beacon verifies only when the follow-up count is lower than the comparable before count. A flat/increased count or an already-low baseline is recorded without closing the Problem or retiring its known error. Raise another governed corrective Change from the retained approved RCA. If the response is lost, the card preserves the original key and evidence identity: use Check saved verification before retrying. A reload performs that check automatically. Do not discard a terminal receipt until you have read its recorded result.

When the check reports not observed, Retry the same verification reuses the frozen key and evidence identity. An unavailable, malformed, or mismatched receipt remains a visible recovery item and never becomes verification proof.

If implementation is recorded as failed or rolled back, Beacon retains that attempt and returns the Problem to approved so you can raise a replacement Change. The published known error remains available; a failed implementation never appears as recurrence verification.

Manual Problems and older active Problems without normalized evidence show Start sealed recurrence measurement. Use it after linking the corrective Change and before implementation. It captures fresh evidence from that point and does not recreate history. Historical records say when no normalized recurrence evidence exists.

Recovering “Mark as used” on a ticket

The ticket’s suggested-knowledge panel records which article you used without changing the ticket’s lifecycle. Recorded confirms that original usage. If the response is lost, use the panel’s check action to establish whether it was recorded. Reloading or returning to the ticket retains the original operation. Retry is offered only after checking and uses the same article and ticket.

A storage failure prevents sending and leaves the action available for recovery. An unavailable article or ticket, or changed permissions, can prevent checking; the panel explains that state instead of treating it as an unrecorded use. Changing tickets or signing in as another operator cannot move the saved use to a different ticket or expose another operator’s recovery result.

Named reviewer search stays expanded within the Knowledge publication handoff and fresh-review request. Its results remain visible while the author reviews other evidence, and failed or unauthorized directory lookup stays explicit. Selecting a directory identity does not publish: the named independent reviewer must open the article and confirm its current version and audience. The requester’s article list has the supported entry route the relevant workflow; searching and choosing an article remain separate from entering that list. Existing drafts, uncertainty recovery, publication receipts, audience confirmation, and correction/expiry controls keep their existing authority.

Complete a repeat correction from a measured Problem

Enter the root cause, internal workaround, and requester-safe workaround in the Problem record. Start, save, and submit RCA for independent review preserves all lifecycle decisions while submitting the displayed evidence once. A separate reviewer approves the current RCA and separately publishes the known error. Your open Problem refreshes after that independent decision.

When a uniquely eligible previous correction exists, review its attributed implementation/backout plans, assessed risk, and current affected scope. Review the new window’s exact start and end. Editing its start retains the displayed duration; it does not retain an old approval. The explicit consent command creates the current linked Change and submits a fresh CAB cycle.

The CAB reviewer opens that Change, reviews its copied plans, risk, window, and approval requirements, and uses Approve this CAB cycle and schedule the exact consented window when approval is complete. The native Change Manager can do this without access to hidden Problem/RCA details. Approve this CAB cycle only is a separate fallback; an authorized Change scheduler then owns scheduling. The retained window shows the consenting author and decision time; that historic consent never supplies a missing current permission.

When the actual approved window begins, the author/implementer uses Begin implementation in the approved window in the retained Problem record. Choose one explicit result command: successful, failed, or rolled back. No result is preselected. Required PIR or other reviews keep the Change in Review; use the linked Change to complete the required independent decision. Review and Closed continue to display the implementation outcome.

After the entire real follow-up window ends, inspect the displayed counts, verify the observed decrease, and close the verified Problem. A flat count, failed correction, unknown old outcome, or missing review does not qualify.

If a command response is lost, keep the saved operation and use Check saved command. Reloading checks its receipt without reissuing the mutation. Read failures remain visible. After a refused stale draft, read/review current evidence before revising; Beacon retains the same key to prevent duplicate effects. Additional recovery navigation and ordinary first-use authoring are additional operator work and must be included when measuring a complete journey.

The independent CAB action for a corrective Change appears on its normal Change record whenever retained correction consent exists. It does not require an approval-recovery warning. CAB can approve and schedule the exact consented window through the Change-scoped action; this does not grant Problem access.