Knowledge Capture Loop

Scope

The four stages of the knowledge loop: capture, deflect, measure and review.

Knowledge Apply receipt implementation (backend/services/knowledge_service.py, backend/services/knowledge_apply_receipt.py, backend/routers/knowledge_base.py, backend/routers/knowledge_portal.py, frontend/src/lib/knowledge.ts).*

Knowledge that never gets written down is resolution effort spent once and thrown away; knowledge that never gets reviewed quietly becomes wrong. Beacon closes both ends as a loop: capture at resolution, deflect at intake, measure what escaped, and review what aged. This page is the operator’s view of that loop end to end.

Capture — at the moment of resolution

• Who: anyone with incidents.promote_kb (service-desk agents, incident managers).

• When: the moment an incident is resolved with resolution notes. The desk prompts you: the Next: line on a resolved incident reads “Capture this resolution as knowledge” whenever no article has been captured from it yet. One click runs Promote to KB and lands you on the new draft. resolved/closed or has no resolution notes. Write down how it was fixed first — that text becomes the article’s ## Resolution section.

• Then: tidy the draft, set the audience (Internal vs Requester portal), add keywords — the words the reader would use, not the ones you did (“password, locked out, signin” on an article titled “Resetting your directory passphrase”) — and Publish (knowledge.publish). Give the article an active directory owner when you save it. Older subject-text owners remain visible as legacy attribution, but cannot request a named publication review.

Deflect — at the moment of intake

Published knowledge does its work before a ticket exists:

• Articles: the portal’s report-an-issue dialog suggests portal-visible articles as the requester types. Multi-word requester queries need at least two matching terms, so one common word can’t drag in the whole library.

• Known errors: a published known error (see “known issue IT is already working on” panel with its workaround. Requesters see the symptom and the workaround only — never the RCA.

• Agents: the desk’s Related tab badges KEDB matches and KB suggestions on ticket open (“6 · KE” means six related records including a known-error match). Each suggested article in that panel carries a Mark as used button — click it once the article actually resolved or helped work the ticket, and it records the usage against the ticket (swapping to a “Recorded” state so you don’t double-record it) — which feeds the review loop below.

Recovering an unconfirmed Mark as used

Beacon saves the original article, ticket and operation reference before a recoverable apply. If the response is lost, keep that original reference and choose Check outcome. A recorded outcome shows the original committed time and cannot be applied again. A missing result means Beacon did not observe a committed receipt; it does not prove the earlier request failed. Use the retry offered for that same saved article, ticket and key rather than clicking a new selection.

If the original article or ticket was deleted, or you no longer have current access to either, Beacon reports the recorded operation as unavailable without showing current target details. Losing Knowledge permission blocks both check could confirm a current result; check again. A conflict message means the saved key and current article/ticket do not describe the same original request; keep the original reference and do not retarget it. If the underlying usage history was removed, the receipt still confirms that the original apply was recorded and never creates a replacement usage.

Measure — what escaped capture

• Resolutions without knowledge capture — incidents resolved in the window from which no article was promoted and to which none was applied, with the ticket list as evidence. This is the loop’s leak, as a number.

• Knowledge capture rate — the complementary percentage.

A knowledge manager’s weekly ritual is opening the evidence list and either promoting the resolutions worth keeping or consciously letting the one-offs go. The deflection metrics (self_service_deflection_rate, XLA scorecard) tell you whether what you captured is landing.

Publish review — who confirms a draft

Publishing a draft can be routed to a named reviewer. Select both the active directory owner and a reviewer, then choose Request review. Beacon records the exact article revision, version and audience with a durable request key. If the request times out or the browser loses its response, keep the draft unchanged and retry the same saved request; do not create a second request to guess whether the first one worked.

Directory selection identifies a person but does not establish permission. The reviewer sees the item in My assigned reviews and must confirm the exact version and audience. Beacon checks current access at that decision. They can publish, reject with a correction, or the requesting author/current owner can cancel. The article keeps its review history. A stale-review message means reload the current article before deciding; it never permits an older version to publish.

Editing published content or its audience creates a draft and withdraws the previous publication. The editor sees that warning and requests a new review. Changing body or summary uses Save new version and adds immutable history; changing only owner, expiry, category, keywords, title, or audience uses Save changes and retains the current content version. A promoted article links its source incident when that incident is inside the reader’s current ticket scope; otherwise Beacon reports that the source is unavailable without leaking it.

Review — what aged

Every article has an owner (defaults to the author), a review date (armed at publish, 180 days) and an optional expiry. Expiry identifies one absolute instant: entering or reading it in another timezone must not extend access to an article. API timestamps include an explicit UTC offset. The hourly knowledge_review_sweep keeps the library honest:

Flag	Meaning	Your move
Review overdue	The review date passed	Re-read it; Review complete re-arms the clock
Unhelpful	≥ 5 reader votes, half or more “not helpful”	Rewrite or archive; read the feedback comments
Contradicted	The article was used on a ticket that later reopened	The resolution it captures demonstrably failed at least once — verify it before trusting it again
(expired)	The author-set expiry passed	The article stops being served immediately; the sweep then archives it (audited). Restore + edit if it should live on

Review complete (knowledge.author) clears the flag and re-arms the review clock. Every sweep action and review completion is on the audit trail.

Permissions quick reference

Action	Permission
Promote an incident, see the capture prompt	incidents.promote_kb
Author/edit, set keywords/owner/expiry, complete a review	knowledge.author
Publish / unpublish / archive	knowledge.publish
Apply an article to a ticket	knowledge.view
Read the summary report metrics	reporting.view

Recovering a bulk Knowledge action

In the Knowledge library, select the articles on the current page and choose Publish, Unpublish, Archive or Restore. Confirmation shows the captured titles and audiences. Above ten targets, type the displayed count. Changes to article evidence or audience after selection are refused; reload and make a fresh selection. A named review still needs its individual reviewer decision.

If the response is lost, keep the Unconfirmed batches reference. Use Check batch outcome to recover the exact original per-article results. A missing receipt does not prove failure. Retry original batch is offered only after a missing-receipt read and sends the same saved request and key. Do not make a new selection to retry an unresolved batch. A corrupt saved request can be checked by reference but cannot be replayed. If local storage cannot retain the request, Beacon refuses to send it.

The recorded report distinguishes changed, already-in-status and refused articles, including bounded refusal explanations. It remains the original batch history when current articles change or disappear. A failed list refresh has its own error; it does not mean the recorded batch failed. References and reports are scoped to your signed account and tenant, and require current Knowledge publication permission. Losing that permission does not authorize reading a previously cached report.