Knowledge Capture Loop

Scope

Knowledge programs fail when capture depends on goodwill. This guide keeps the loop that makes capture part of resolution and measures the gaps.

Last verified: 2026-08-15 against the KNB-1 implementation (backend/services/knowledge_service.py, backend/routers/knowledge_base.py, backend/routers/knowledge_portal.py, frontend/src/lib/nextAction.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).

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 (KNB-1): 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), and the Apply action on an article records that you used it on the ticket — which feeds the review loop below.

Measure — what escaped capture

(Reports → Summary) carries two KNB-1 metrics:

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

Review — what aged

Every article has an owner (defaults to the author), a review date (armed at publish, 180 days) and an optional expiry. 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	Nothing — the sweep archived it already (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