> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mine deflection gaps into knowledge base additions

> Read the Deflection Gaps page — the clustered list of customer questions your AI failed to answer — and turn each cluster into a reviewed, published KB article with the guided KB-add chip.

# Mine deflection gaps into knowledge base additions

Every time a customer asks your AI something it cannot answer — because the
knowledge base has no candidate article, or because the best candidate's
match confidence lands below the threshold — Orbit records the question as a
**deflection miss**. The Deflection Gaps page groups those misses into
clusters so you see "46 contacts asked about refund timing — your KB has no
article" instead of 46 separate log lines, then hands you a guided chip to
draft the missing article directly from the cluster.

This guide covers **Agents → Knowledge base → Gaps** in the dashboard
(`/agents/knowledge-base/gaps`) and the two API endpoints behind it. It
closes the loop that
[Auto-draft help articles from resolved conversations](/guides/kb-auto-draft)
starts: auto-draft mines conversations your AI *resolved*; the gap miner
surfaces the questions it *missed*.

## Where the gap panel fits

Open **Agents → Knowledge base**, then choose the **Gaps** view. The page
header shows the total miss count for the current window and the number of
clusters, with two controls:

* **Look-back window** — 7 to 90 days (default 30). Everything below is
  computed inside this window.
* **Cluster count** — how many clustered misses to list (default top 10).

Each cluster row shows the representative customer question, the miss count
(the raw number of recorded misses in the cluster), the distinct conversation
count, a suggested topic chip, and the most recent customer questions
verbatim. A cluster is the unit of work: you promote the whole cluster into
one draft article, not one question at a time.

The same data is available over the API:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/inbox/knowledge-gaps?days=30&limit=10" \
  -H "X-API-Key: dv_live_sk_..."
```

The response is a report `{ days, total_misses, clusters }` where each
cluster carries `cluster_id`, `representative_query`, `miss_count`,
`conversation_count`, `suggested_topic`, and up to three `recent_examples`.
`total_misses` is the true miss count for the window — it is not capped by
the clustering sample, so use it for the badge number, not the cluster sum.

## What counts as a miss — the two signals

A miss is recorded the moment the deflection ranker fails a customer's
question, in one of two shapes:

1. **No candidate** — the ranker found nothing in the attached knowledge
   base that could answer the question. The KB lacks the topic entirely.
2. **Low confidence** — a candidate article existed but the match confidence
   came in below the publish threshold, so the customer was escalated
   instead of answered. Topic-adjacent material exists, but it does not
   actually resolve the question.

Both shapes tell a KB author the same thing — *write an article here* — but
the first is a coverage gap and the second is a resolution-quality gap. The
Deflection Gaps page deliberately shows the union.

A companion signal lives on the knowledge-base-scoped endpoint
`GET /api/v1/agents/knowledge-bases/:id/gaps`: that one derives gaps from
assistant turns that contained "I don't have that information"-class
phrasing, or from conversations escalated to a human. The deflection-miss
report above is captured synchronously at the moment of failure; the
per-knowledge-base report catches the same failures from the agent
conversation side. Check both when a cluster seems thin — the gap you are
looking for may be filed under the other signal.

## How clustering works

Misses are grouped by token overlap: each question is tokenized (stopwords
and punctuation stripped), and two questions join the same cluster when
their token sets overlap at a Jaccard similarity of 0.4 or higher. Clusters
sort by miss count, with the conversation count breaking ties, so the
highest-impact gap sits on top.

Every cluster carries a **suggested topic** — the highest-frequency
meaningful token across the cluster's questions. It is not the article
title; it is the starting hint for the article's slug. A cluster whose top
token is `refund` is telling you where to file the article, not what to name
it.

The `cluster_id` on each cluster is a stable hash of the cluster's tokens.
Re-running the same window over the same data yields the same id, which is
what lets the promote endpoint (below) re-derive the cluster from the id
alone. It also means the id is only valid inside the window you listed —
change `days`, and the same cluster carries a different id.

## Promote a cluster into a draft article

In the dashboard, pick the knowledge base the new article should land in
from the header dropdown, then click **Create draft article** on a cluster.
Orbit drafts an answer card from the cluster's real customer questions —
the title seeded by the suggested topic, the body built from what customers
actually asked — and uploads it into the selected knowledge base as a
**draft** document. You are then deep-linked into that knowledge base to
review it.

Over the API:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/inbox/knowledge-gaps/9f4c1a2b3d4e5f60/promote" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_id": "kb_0123456789abcdef0123456789abcdef",
    "title_hint": "Refund timing after cancellation",
    "days": 30
  }'
```

* **`knowledge_base_id`** (required) — the target knowledge base. Promote
  never creates a knowledge base for you; which base a gap belongs to is a
  content organization decision only you can make. If the workspace has no
  knowledge base yet, create one first.
* **`title_hint`** (optional) — nudges the drafted title toward the angle
  you already have in mind. The suggested topic chip is the dashboard's
  seed for this field.
* **`days`** (optional, default 30) — must match the window you listed the
  cluster under. The endpoint re-runs the clustering pass and looks the
  cluster up by id, so a `days` mismatch (or a window so old the cluster
  aged out) returns a 404 that says the cluster was not found in the
  selected window.

The response echoes the new `document_id`, the draft `title`, and the
`source_cluster` it came from. Promoting is a write action — it requires an
owner, admin, or developer role, same as editing knowledge base content.

## Review and publish

The promoted cluster lands as a **draft** — the same pending-review state
the auto-draft pipeline uses. A draft never grounds a live AI answer: its
content is not embedded and not retrievable until a human approves it.

Review the draft in **Agents → Knowledge base**:

1. Open the draft document. The body lists the verbatim customer questions
   from the cluster — treat it as raw material, not a finished article.
2. Rewrite the body into the answer customers should receive, filling in
   the facts the drafter could not know (policies, windows, prices).
3. **Approve** the document. Approval embeds its chunks, making the article
   retrievable by every agent attached to that knowledge base — the next
   customer who asks the clustered question gets the answer instead of an
   escalation.
4. Or **reject** it when the cluster was noise.

The same lifecycle is available over the API —
`POST /knowledge-bases/:id/documents/:docId/approve` and
`POST /knowledge-bases/:id/documents/:docId/reject`. The full document
lifecycle is in
[Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle).

## The two mining loops work together

The Deflection Gaps page and the auto-draft pipeline cover opposite halves
of the same loop:

* **Auto-draft** mines *resolved* conversations and drafts articles for
  recurring reasons the analysis flags as best covered by a help article.
* **Deflection gaps** capture the questions that were *not* resolved — the
  ranker missed and the customer escalated — and let you promote those
  clusters into drafts.

Both pipelines land drafts in a knowledge base behind the same human review
gate, and both respects per-topic dedup through your review decisions.
Running both is the intended steady state: auto-draft fills the articles
for what your AI handles, gap-mining fills the articles for what it misses.
See [Auto-draft help articles from resolved
conversations](/guides/kb-auto-draft) for the auto-draft configuration.

## Diagnostics — when clusters or suggestions stop appearing

**The page is empty but customers are escalating.** The window may be too
short — widen the look-back dropdown. If it is still empty, no deflection
misses were recorded in the window at all: either the knowledge base really
is covering everything, or no agents ran deflection in the period. Check
the companion per-knowledge-base report
(`GET /agents/knowledge-bases/:id/gaps`) which picks up the same failures
from the assistant-turn side.

**A promote returns 404 with "cluster not found".** The cluster id only
resolves inside the window it was listed under. Re-list the gaps with the
same `days` value, take the current `cluster_id`, and promote that. A
cluster also ages out naturally — once its misses fall outside the window,
the id no longer resolves. This is by design: the drafts always build from
recent questions, not stale ones.

**The same cluster reappears after you promoted it.** Promoting files a
draft but does not delete the underlying misses — they stay in the window
until they age out. If you do not want to see the cluster again, approve or
reject the draft: the published article starts absorbing the traffic, and
the rejected draft marks the topic as reviewed.

**Miss counts look stuck at the window cap.** The clustering pass samples
the most recent misses in the window and the cluster list is intentionally
bounded; `total_misses` keeps the true count. Raise `limit` (up to 50
clusters) to see more clusters, or shorten the window to re-rank.

## See also

* [Auto-draft help articles from resolved conversations](/guides/kb-auto-draft) — the resolved-conversation half of the loop
* [Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle) — the document review/publish lifecycle
* [AI agent rollout pipeline](/guides/ai-agent-rollout-pipeline) — attach the published knowledge base to agents