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

# Close knowledge gaps

> Use the Gaps screen to find the recurring questions your AI agent could not answer, write the article that covers them, and confirm the gap closes.

Every question your agent could not answer is a documentation request you did not have to write yourself. Knowledge Gaps groups those escalations into recurring topics, ranks them, and gives you a list of what to write next.

This is the weekly loop that makes an AI agent get better instead of plateauing.

<Callout icon="flask-conical" color="#7C3AED">Knowledge Gaps is in private beta. Ask the team on Slack or in-app chat for access.</Callout>

<Steps>
  <Step title="Open Knowledge > Gaps">
    Gaps are cards, one per topic, sorted by recent activity and severity. Each card shows:

    * A **ticket count** in a severity-colored circle
    * The gap's **label and description**, generated from the tickets in it
    * A **trend pill**: red and rising, green and falling, grey when steady
    * When the topic was **last mentioned**

    Click a card to expand it and see the actual tickets: who asked, the ticket ID, and which channel it came from. Read those before you write anything. The label is a summary, and the tickets are the requirement.
  </Step>

  <Step title="Pick what to write, in this order">
    Sort by judgment, not just severity:

    1. **Critical or High with a rising trend.** Growing problems get worse while you deliberate.
    2. **Anything classified as no content exists.** The agent searched and found nothing, so one article fixes every future instance.
    3. **High volume, flat trend.** Steady, predictable pain. Easy wins.

    Skip **declining** gaps. They sink on their own, and a falling trend usually means something already changed.

    <Tip>
      Severity is 60% volume and 40% trend, with volume saturating around 150 tickets. That means a smaller, fast-growing topic can and should outrank a bigger stagnant one. Trust the ordering.
    </Tip>

    <Callout icon="link" color="#6B7280">Learn more about [severity and trend](/documentation/automate/knowledge/knowledge-gaps#severity-and-trend)</Callout>
  </Step>

  <Step title="Check Watching for what is coming">
    Set the **State** filter to **Watching** to see escalations that resemble each other but have not accumulated enough volume to be a confirmed gap yet. They are listed as loose tickets, with how many detection runs each has survived.

    This is the most useful screen in the feature and the least used. It shows you a new product area or an edge case weeks before it becomes a Critical gap. A stray that goes 21 days without gathering companions ages out on its own.

    One thing that explains most "why is this not showing up" confusion: **tickets where the agent never attempted a knowledge lookup are never pooled.** They do not appear in Watching and they do not become gaps.
  </Step>

  <Step title="Write the article">
    Write it yourself in your knowledge base, covering the topic the gap names. If a specific ticket already contains the full question and the answer, you can generate a first draft from it instead:

    * **In Slack**, react to the original channel message with 🧠. Not a thread reply, the original message. If a ticket does not exist for the thread, Ravenna creates one. React again later and it updates the same article rather than duplicating it.
    * **In the Admin**, open the ticket, use the **⋯** menu, and select **Generate KB Article**.

    Generated articles are drafts. They are ingested and immediately searchable by agents with access to the parent folder, which means a bad draft is a bad agent answer. Review before you leave it.

    Generation can finish without producing an article, usually because the conversation contained no real gap.

    <Callout icon="link" color="#6B7280">Learn more about [generating KB articles](/documentation/automate/knowledge/generate-articles)</Callout>
  </Step>

  <Step title="Confirm the gap actually closed">
    There is nothing to close by hand. Once the content is published and the agent starts resolving those questions, the gap picks up a **Resolved** badge and its trend falls on the next detection run.

    If the trend does not move, the article is not being retrieved. The usual causes are all fixable:

    * The article is in a folder the agent's knowledge scope does not include
    * The article buries the answer in a screenshot or a wall of context
    * The title does not match how employees phrase the question

    <Callout icon="link" color="#6B7280">Learn more about [structuring knowledge for AI](/guides/best-practices/knowledge-for-ai)</Callout>
  </Step>

  <Step title="Make it a weekly habit">
    Detection runs weekly per workspace. Match your cadence to it: fifteen minutes once a week, write one or two articles, move on.

    Use **Sync** on the Gaps tab to force an immediate run, which is worth doing once on a new workspace so you are not waiting a week for the first results.
  </Step>
</Steps>

## Things that look like bugs but are not

<AccordionGroup>
  <Accordion title="Severity changed with no new tickets">
    Expected. The comparison window is a trailing 30 days that slides forward with today, so a bucket can drop purely because older activity fell out of the window.
  </Accordion>

  <Accordion title="A gap's label looks dated">
    Labels only refresh after a cluster has grown meaningfully since the last relabel. A cluster that stopped growing keeps its old wording, deliberately, to avoid churn.
  </Accordion>

  <Accordion title="An obviously repeated question is not listed">
    Check three things: it may still be in **Watching**, the agent may never have attempted a lookup on those tickets, or your severity toggles may be filtering it out. A gap hidden by a severity toggle looks identical to one that does not exist.
  </Accordion>

  <Accordion title="Nothing at all in Gaps">
    On a new workspace, results appear after the first scheduled run. Use **Sync** to force it.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Knowledge for AI" icon="brain" href="/guides/best-practices/knowledge-for-ai" horizontal>
    How to write source docs the agent can actually retrieve.
  </Card>

  <Card title="Reporting and briefs" icon="chart-line" href="/guides/playbooks/reporting-and-briefs" horizontal>
    Watch the resolution rate move as gaps close.
  </Card>
</CardGroup>


## Related topics

- [Knowledge for AI](/guides/best-practices/knowledge-for-ai.md)
- [Policy and compliance questions](/guides/playbooks/legal/policy-and-compliance.md)
- [Reporting and briefs](/guides/playbooks/reporting-and-briefs.md)
- [Go live](/guides/day-one/go-live.md)
- [Guides](/guides/overview.md)