> ## Documentation Index > Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt > Use this file to discover all available pages before exploring further. # Knowledge gaps > Automatically detect recurring topics your knowledge base does not cover well, ranked by severity and 30-day trend so you know what to document next. Knowledge Gaps is currently in private Beta and enabled for selected customers. If you'd like access, reach out to the team on Slack or via the in-app chat. Knowledge Gaps looks at tickets your AI agent could not resolve, groups the similar ones together, and surfaces them as prioritized recurring topics your knowledge base doesn't cover well yet. Instead of skimming escalations by hand, you get a ranked list of what to document next that refreshes automatically each week. Each gap (a **cluster**) has: * A **severity** bucket (Low, Medium, High, or Critical) driven by ticket volume and 30-day trend. * A **classification** of why it's a gap: no content exists, or content exists but wasn't sufficient. * Example tickets, an item and problem type, and a lifecycle state so you can see whether it's growing, quiet, or archived. Find it under **Knowledge > Gaps**. *** ## Views The Gaps tab has three mutually exclusive views. Click any summary stat at the top to switch. | View | What it shows | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Open** | Active gaps in the current date range, ranked by severity and volume. | | **Archived** | Gaps that have gone quiet (no new tickets in 90+ days) and were not marked as covered. | | **Emerging** | Rare or early signals: questions that resemble each other but haven't yet hit the volume needed to be called a confirmed gap. | Filter open gaps by severity, search by label or example question, and set a date range from the header. *** ## How gaps are detected Detection runs automatically on a weekly cycle, per workspace. Each run pulls escalated tickets since the last successful run, matches them against existing gaps, clusters what remains, splits mixed-topic clusters, classifies each cluster, and recomputes severity, trend, and lifecycle for every gap in the workspace. ```mermaid theme={"system"} graph TD A(Weekly run starts) --> B(Pull escalated tickets
since last successful run) B --> C{Matches an
existing gap?} C -->|Yes| D(Add to that gap) C -->|No| E(Cluster remaining tickets
into new gaps) E --> F(Split any cluster mixing
distinct products or systems) F --> G(Classify each cluster:
no content / weak content / not a gap) D --> H(Recompute severity, trend,
and lifecycle for every gap) G --> H H --> I(Run complete) classDef question fill:#E2EAEF,stroke:#165d6e,stroke-width:1px,color:#0f172a classDef step fill:#269cbd,stroke:#269cbd,color:#ffffff classDef terminal fill:#165d6e,stroke:#165d6e,color:#ffffff class C question class B,D,E,F,G,H step class A,I terminal ``` If a scheduled run is still finishing when the next one is due, the next run is skipped rather than queued behind it. Runs that fail don't advance the watermark, so the next run automatically re-covers the same window with no gaps or double-processing. ### What counts as an escalation An escalation is any ticket where the AI agent could not resolve the customer's question. For each one, detection records: * **Knowledge-base signal**: whether the agent tried a KB lookup and what came back. * **No content**: searched and found nothing. * **Had content**: searched and found something, but it didn't resolve the question. * **Not searched**: the agent never attempted a lookup. * **Item and problem type**: the product or system involved and the kind of problem, extracted from the ticket. Synonyms and casing are canonicalized so one gap doesn't silently swallow unrelated topics with similar wording. * **Queue and agent attribution**: for per-queue reporting. ### Running detection on demand Use **Sync** from the Gaps tab to force an immediate run using the same pipeline as the weekly schedule. *** ## Severity and trend Every gap gets a severity bucket, recomputed on every run from ticket volume and 30-day trend. ```mermaid theme={"system"} graph LR V(Volume score
caps at ~150 tickets) -->|60%| S(Severity score
0 to 100) T(Trend score
flat = neutral) -->|40%| S S --> L{Bucket} L -->|score ≥ 75| C1(Critical) L -->|50 to 74| C2(High) L -->|30 to 49| C3(Medium) L -->|below 30| C4(Low) classDef input fill:#E2EAEF,stroke:#165d6e,stroke-width:1px,color:#0f172a classDef question fill:#E2EAEF,stroke:#165d6e,stroke-width:1px,color:#0f172a classDef step fill:#269cbd,stroke:#269cbd,color:#ffffff classDef terminal fill:#165d6e,stroke:#165d6e,color:#ffffff class V,T input class L question class S step class C1,C2,C3,C4 terminal ``` **How volume and trend combine:** * **Volume** contributes 60% of the score. It saturates once a cluster hits about 150 tickets. Beyond that, more tickets don't raise volume further. * **Trend** contributes 40%. Trend is the percentage change in new tickets over the last 30 days compared with the prior 30 days. * A flat cluster scores neutral, so it isn't rewarded or penalized. * A growing cluster scores higher and can rank above a bigger but flat one. * A declining cluster scores lower and sinks in the list on its own. * New clusters without prior-window history are treated as flat, so they aren't penalized or inflated on their first appearance. Trend is computed from each ticket's real escalation date, not the date the ticket was processed. A ticket that escalated three weeks ago but only joined a cluster today (through the Emerging pool) counts on the date the customer actually hit the issue. A gap's severity can change even with no new tickets. The scoring window slides forward in time with "today", so an unchanged cluster can drop a bucket purely because comparable activity fell out of the trailing 30-day window. This is expected. *** ## Emerging topics Some escalations are too rare or too early to hit the clustering threshold on their first pass. Rather than being dropped, they're held in a pending pool and automatically re-fed into every subsequent weekly run. Once enough similar tickets accumulate, they graduate into a real, visible gap. * Shown in the **Emerging** view, framed as "not a confirmed gap yet, but showing up." * A stray that goes 21 days without gathering enough companions ages out. * Tickets where the agent never attempted a KB lookup are never pooled. Use the Emerging view to spot new product areas or edge cases before they get large enough to hurt. *** ## Cluster lifecycle Every cluster has a lifecycle state that's maintained automatically as part of each weekly run. ```mermaid theme={"system"} graph LR A(Active) -->|30+ days idle| D(Dormant) D -->|90+ days idle| R(Archived) D -->|New tickets| A R -->|Manual restore| A A -->|Manual archive| R classDef live fill:#165d6e,stroke:#165d6e,color:#ffffff classDef idle fill:#E2EAEF,stroke:#165d6e,stroke-width:1px,color:#0f172a classDef archived fill:#F1F5F9,stroke:#94a3b8,color:#475569 class A live class D idle class R archived ``` | State | Meaning | How it's reached | | ------------ | ----------------------------------------------------- | -------------------------------------------------- | | **Active** | Normal, in-rotation gap. Ranked and visible in Open. | Default on creation and while getting new tickets. | | **Dormant** | No new tickets in 30+ days, but not yet archived. | Automatic sweep. | | **Archived** | No new tickets in 90+ days and not marked as covered. | Automatic sweep, or manual archive from the gap. | Labels and descriptions are refreshed automatically once a cluster has grown meaningfully since it was last labeled, so the name stays accurate as more tickets land in it. A cluster that has stopped growing keeps its existing label even if it feels dated. Label refresh only fires after meaningful new growth. This is intentional to avoid churn on stable clusters. *** ## What you can do with a gap Open any gap to see its label, description, example tickets, item and problem type, ticket volume, severity, trend, and lifecycle state. From there you can: * **Generate a KB article** from the cluster. This uses every ticket in the gap to draft a single, comprehensive article covering the topic. * **Open example tickets** to see the underlying customer questions and confirm the cluster matches what you'd expect. * **Archive** a gap manually if you have already resolved it or if the topic is no longer relevant. Learn more about [generating a KB article from a gap](/documentation/automate/knowledge/generate-articles#from-a-knowledge-gap-cluster) *** ## Common issues Detection is a weekly cycle. On a brand-new workspace, results appear after the first scheduled run. Use **Sync** to force an immediate first run if you don't want to wait. Most likely it's still in the **Emerging** view because it hasn't accumulated enough tickets yet, or the agent never attempted a KB lookup on those tickets (which routes them out of the gaps list entirely), or the tickets fall outside your current date range. Labels only refresh after a cluster has grown meaningfully since its last relabel. A cluster that has stopped growing keeps its old wording. This is expected. Expected. Severity uses a trailing 30-day comparison window that slides forward with today, so a bucket change without new activity is the math working, not a bug. Live coverage status isn't wired up in the current Beta. Every gap displays the same default coverage state. This is on the roadmap. *** ## Glossary * **Gap / cluster**: a group of similar customer questions that the knowledge base doesn't currently answer well. * **Severity**: Low, Medium, High, or Critical, driven by ticket volume and 30-day trend. * **Trend**: the 30-day change in how often a topic is coming up, compared with the prior 30-day window. * **Emerging**: questions that resemble each other but haven't yet reached enough volume to be called a confirmed gap. * **Archived**: a gap that has gone quiet for 90+ days and was either resolved or naturally faded.