Gaps

/admin/ai/support/gaps. Every row in the list at the bottom is a question a real customer asked that your knowledge base could not answer, sorted by how many people asked it.

That list is the answer to "what should I document next", and it is worth more than any content plan you could write, because it is demand rather than guesswork. Four panels sit above it, and each answers a different question about the same corpus:

What a row tells you

A gap card shows three things and no more:

• The count, in the square on the left. How many times this question was recorded.
• The question, in the customer's own words. The most recent phrasing of it, not the normalised form. Rows are deduplicated on a fingerprint built by lowercasing the question, dropping stop words and sorting what is left — so "how do I enable 2FA" and "enable 2FA, how do I?" are one row. That fingerprint reads like "account how verify" and is never shown; it is only the fallback for rows recorded before the sample was kept.
• A "Nearly matched" badge, when the best score any source has ever reached for this question cleared 0.15. The numeric score is not printed.

Read the badge as the difference between two jobs. A high count with no badge is a topic you have never written about — write it. A high count with the badge is usually a topic you have written about, in the wrong words; fix the article rather than write a new one, and check it against the retrieval tester on Sources.

There is no "first seen" on the card. The row is a running total, not an event: each time the question comes back, the count goes up, the stored sample is replaced with the newest phrasing, and the best score is raised if this attempt got closer.

What you wrote badly

Documentation your customers say is wrong sits directly under coverage, and it is the only quality signal in the whole addon that comes from a person.

Everything else the assistant records is the machine grading itself. Retrieval score says it found something. Groundedness says the text it produced was supported by the passages it was given. The citation count says it attributed its claims. All three are perfectly high on an answer that is confidently, completely wrong, because all three measure internal consistency rather than truth. A thumbs-down is a customer saying it did not help.

The unit is the passage, not the answer. An operator cannot fix "answer #4812"; they can fix the page it came from. So every thumbs-down is attributed back to every passage that was in front of the model when that answer was written — not only the ones it cited. That is deliberately generous: nobody knows which of the six the model actually leant on, and blaming the cited ones alone would miss the case where the real problem is a passage that crowded out the right one.

The consequence is that a popular but perfectly good passage collects votes simply by being retrieved often, so the ratio matters and the raw count does not:

Each row shows the passage title, its breadcrumb, a badge with its source kind, and the share against it — "67% unhelpful (4/6)". The source kind is the actionable part:

• ARTICLE or FAQ — yours. Open it and fix the sentence.
• DOCS_PACK — shipped product documentation you cannot edit. The action there is to write an article of your own that outranks it; your articles carry more retrieval weight than the packs do.

Coverage

What your documentation can answer is the first panel, and the only thing on the screen that says how the assistant is doing overall. It is a button, not a number that loads with the page: press Measure now.

It replays up to two hundred subject lines from your recent tickets — distinct, and ignoring anything under twelve characters, because "help" and "urgent" measure nothing — against your own index, applying the same two gates the assistant applies at answer time. Not a single model call: retrieval runs without the reranker here, so unlike the tester on Sources this really is free. It is not instant, though, which is why it does not run on load.

The headline is "N% answerable from your own documentation". Under it is the part that matters: the specific questions that failed, each tagged Needs your own policy or Not documented, with a projection — "Writing the 6 below would take you to 88%." "You are at 72%" is a fact nobody can act on; a list of six questions with a stated result is a morning's work.

Two empty states, and they mean opposite things: "No support tickets yet" is a new install working correctly, and "Your knowledge index is empty" is a broken one — go and rebuild the index from Sources.

Closing a gap without leaving the screen

Publishing happens inline, and that is deliberate: a screen that only reports problems and sends you somewhere else to fix them gets read once. One where reading and fixing are the same action gets used.

You can also Ignore a row — the eye icon beside Answer — for a question you are never going to answer, or one that should always reach a person. It removes the row from the list without writing anything, and does not change what the assistant does with the next customer who asks: it will still escalate.

Drafts waiting for you

Anything the drafters have written appears above the gap list as a review queue, badged AI draft, ordered by the gap's count so the answer twenty people are waiting for is reviewed before the one somebody asked once.

The answer is editable in place. A review screen that only offers approve and reject makes you leave, find the article, fix one sentence and come back, which is the friction that stops knowledge bases being maintained.

• Publish writes the draft that is already attached rather than creating a second article saying the same thing.
• Discard deletes the draft and puts the question back on the gap list, so drafting again starts clean.
• A draft whose article was deleted elsewhere is shown as "The draft for this question was deleted from your knowledge base" with a Put back on the list button, rather than being silently dropped — the gap would otherwise sit in DRAFTED for ever, invisible on both lists.

Two things feed this queue, and both save you writing from scratch:

• Answers your agents already wrote. A nightly job reads the tickets your team handled by hand and files good replies as draft articles. The questions you answer twice become questions that answer themselves.
• Drafts from your documentation. The Draft answers button re-retrieves each open gap against today's corpus and drafts only where the documentation now supports one.

Both are covered in full on Teaching, including what each costs and why every one of them lands as a draft.