> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge Gaps
> Check shipped releases against your documentation sources and review findings for missing, stale, or hard-to-find docs
Knowledge Gaps (`/success/knowledge-gaps`) answers one question: **did the docs keep up with what we shipped?**
It takes the shipped releases already collected for [Releases / Close the Loop](./close-the-loop), searches your configured documentation sites for pages that cover each release, and asks a classifier whether a documentation update is actually needed. Anything that looks like a gap lands in a review queue with the release evidence, the docs that were checked, a suggested change, and a copy-ready prompt for drafting the update.
Knowledge Gaps is gated by two flags: the `success` feature flag and the `knowledge_gaps` feature flag. Both must be enabled for the workspace or the page, the API, and the background worker all return an empty state.
## What It Produces
Each finding in the queue carries:
* **Release evidence** — the changelog entry, GitHub release, or extracted feature that triggered the check, with its date and source link.
* **Documentation checked** — up to 8 pages matched from your active documentation sources, each with a match percentage and excerpt.
* **A gap type** — missing docs, stale docs, hard to discover, UX confusion, missing feature, or needs triage.
* **Urgency and impact score** — how worth doing this looks relative to everything else in the queue.
* **Suggested update** — a plain-English description of the change to make, tailored to the gap type.
* **A prompt** — the full finding packaged as a documentation-writing (or triage) prompt you can copy into any AI tool.
## Setup
Turn on both `success` and `knowledge_gaps` for the workspace. Knowledge Gaps then appears in the Success nav, and the Knowledge Gaps cards appear in **Settings -> Features -> Success**.
In **Settings -> Features -> Success -> Release sources**, connect a GitHub repository (releases and tags) and/or an RSS changelog feed. These are the same release sources Close the Loop uses, and they are what Knowledge Gaps analyzes. Without shipped releases there is nothing to check documentation against.
In **Settings -> Features -> Success -> Documentation sources**, add the root URL of each docs site or help center. For each source, set:
* **Source name** — defaults to the hostname if left blank.
* **Root URL** — must be `http` or `https`. Only pages under this root are considered matches.
* **Audience** — **Customer docs** or **Internal docs**.
Audience matters: the classifier is deliberately strict about customer-facing docs and will not recommend a customer docs update for a backend refactor, a reliability fix, or a single-tenant issue. Mark internal enablement, support runbooks, and engineering docs as **Internal**.
Use either entry point:
* **Analyze latest releases** on the Knowledge Gaps page — runs the parent releases shipped since the last run, up to 25 at a time, against every active source.
* **Knowledge Gaps backfill** in Success settings — lets you pick the scope and evidence mode, shows a credit estimate, and confirms before spending.
Analysis runs on a background worker. Findings appear in the queue as each release finishes.
Knowledge Gaps never runs on its own. Nothing is analyzed until someone clicks **Analyze latest releases** or **Run backfill**, so the queue only reflects releases you have explicitly paid to check.
### Managing Documentation Sources
| Action | Notes |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| **Add** | Adding a root URL that already exists updates the existing source instead of creating a duplicate. |
| **Edit** | Change name, root URL, or audience. Changing the root URL to one already in use is rejected. |
| **Remove** | Removes the source from future analysis. Existing findings keep their recorded evidence. |
| **Preset sources** | Sources marked **Preset** cannot be edited or removed. |
Only **active** sources are used. The page header shows how many are configured and splits them into customer versus internal.
## Backfill Scope and Evidence
The backfill card in Success settings controls which releases get analyzed.
| Scope | Releases considered |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Since last run** | Everything shipped after the most recent analyzed release for this source configuration. The default. |
| **Last 30 days** / **Last 90 days** | A rolling window. |
| **All history** | Every shipped release on record. |
| **Custom range** | A specific start and/or end date. |
| Evidence mode | What counts as one item |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| **Parent releases** | One item per release or tag. The default, and what **Analyze latest releases** uses. |
| **Extracted features** | One item per individual feature parsed out of a release. Finer-grained and more expensive. |
| **All release rows** | Both parent releases and extracted features. |
Before running, the estimate shows **Eligible**, **Already analyzed**, **Remaining**, **Estimated credits**, and **Estimated cost**, plus the release window and the date of the last analyzed release. Releases already analyzed against the same set of documentation sources are skipped and are never charged twice.
A run analyzes at most 50 releases (the UI batches 25). Run it repeatedly to work through a large backlog — each run picks up where the last one stopped.
## How Analysis Works
Releases are pulled for the chosen scope and evidence mode, then filtered against the set already analyzed for the current documentation-source configuration. Changing which sources are active produces a new configuration, so previously analyzed releases become eligible again.
The batch is gated on available credits before any work starts. If credits cover only part of the batch, the run is trimmed rather than failing; if none are available, the run is rejected with a clear error.
For each release, BuildBetter searches every active documentation source for pages relevant to the release text, keeping up to 8 matches with a confidence score each. Results are restricted to URLs under the source's root. If live site search is unavailable, previously indexed pages for that source are searched instead.
The release evidence, the matched pages, and the source audiences go to an AI classifier that returns a gap type, a 0-100 confidence score, a one-line summary, and a rationale that has to cite the actual evidence and pages. The classifier is told to prefer **Needs triage** over inventing a gap when a release note is too thin to tell whether customers are affected, and to treat changelog pages as evidence rather than as the page to update. Classification times out after 45 seconds and falls back to a deterministic heuristic.
A `no_gap` result creates no queue item — and if a finding already existed for that release and source set, it is marked **Done** with the reason "Analysis found no active documentation gap." Anything else is written to the queue as a pending finding.
Findings are keyed by a hash of the organization, the release evidence, and the exact set of documentation sources. Re-analyzing the same release against the same sources updates the existing finding instead of creating a duplicate.
## Gap Types
| Gap type | Shown as | Meaning |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `missing_documentation` | **Missing docs** | No relevant page exists and the release needs coverage. |
| `stale_documentation` | **Stale docs** | A related page exists but likely describes outdated behavior. |
| `hard_to_discover` | **Hard to discover** | A relevant page exists but users would not find it from the language in the release. |
| `ux_confusion` | **UX confusion** | Docs should clarify a confusing workflow. |
| `missing_feature` | **Missing feature** | This is a product capability gap, not a docs gap. |
| `insufficient_evidence` | **Needs triage** | Not enough context to decide; ask product or engineering first. |
| `no_gap` | **No gap** | Docs already cover the release. Does not create a new queue item. |
## Urgency and Impact
Every finding gets an impact score from 0-100 that blends the gap type with the classifier's own confidence, plus a bonus when a real docs page (not just a changelog entry) was matched. That score becomes an urgency badge:
| Urgency | When |
| ---------- | --------------------------------------------------------------------------- |
| **High** | Impact 68 or above, still pending. |
| **Medium** | Impact 40-67, or the finding is already approved or attached. |
| **Low** | Impact under 40, or the finding is done, declined, no-gap, or needs triage. |
Findings where the **only** match was a changelog or release-notes page are capped low and labeled **Needs docs target** — the release shipped, but there is no product documentation page to point at yet.
## Working the Queue
The queue opens on **Pending** and offers tabs for **Approved**, **Done**, **Declined**, and **All**, each with a live count.
**Filters and sort:**
* Free-text search across release titles, rationale, matched page titles, source names, URLs, and excerpts.
* Urgency filter (high / medium / low).
* Gap type filter.
* Sort by **Recommended** (urgency first, then least-covered), **Newest**, **Highest impact**, or **Needs triage**.
Selecting a card opens the detail panel with **Why this is here**, the full release artifact, every documentation page that was checked, the suggested update, and the copyable prompt.
### Review Actions
| Action | Effect |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Approve** | Moves the finding to Approved — you have agreed the docs work is real. |
| **Decline** | Moves the finding to Declined with an optional reason. |
| **Mark done** | Available after approval. Records "Documentation update completed." |
| **Check again** | Re-runs analysis against the current documentation sources, preserving the review state. If the recheck finds no gap, the finding is marked Done with the reason "Recheck found no active documentation gap." Useful right after publishing the fix. |
| **Delete** | Removes the finding from the queue. A later analysis run can regenerate it. |
| **Open best match** | Opens the highest-confidence matched page in a new tab. |
The fastest loop is: approve → copy the prompt → draft and publish the docs update → **Check again**. The recheck re-searches your live docs site, so a published page closes the finding automatically instead of relying on someone remembering to mark it done.
## Projects Integration
Project detail pages show a **Knowledge Gaps** card summarizing that project's findings, with a link that deep-links into the queue filtered to the project (`/success/knowledge-gaps?projectId=`). Attaching a finding to a project sets its status to **Attached**, which is grouped with Approved in the queue tabs.
## Billing
Knowledge Gaps analysis is metered as **Success Knowledge Gaps** on the organization billing page.
| | |
| ---------------- | ------------------------------------------------------------------------------- |
| **Rate** | 48 credits per analyzed release |
| **Credit price** | $0.001 per credit (about $0.048 per release) |
| **Not charged** | Releases already analyzed against the same documentation-source configuration |
| **Charged** | Every release the run actually analyzes, including ones that come back `no_gap` |
The backfill confirmation dialog itemizes scope, evidence mode, releases in this run, credits for this run, and the total estimate for the selected scope before anything is spent.
## API
All endpoints are under `/v3/rest/success/knowledge-gaps` and require both feature flags; otherwise they return `403`.
| Method | Path | Purpose |
| -------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/sources` | List documentation sources. |
| `POST` | `/sources` | Add a source (`provider`, `name`, `rootUrl`, `audience`, optional include/exclude patterns). |
| `PATCH` | `/sources/:id` | Update a non-preset source. |
| `DELETE` | `/sources/:id` | Remove a non-preset source. |
| `GET` | `/recommendations` | List findings. Filters: `status`, `statuses`, `statusGroup` (`approved` / `not_approved`), `gapType`, `projectId`, `limit` (0-200). Returns findings plus a status summary. |
| `POST` | `/analysis` | Queue an ad-hoc analysis from supplied `evidence` and/or `queryText`. |
| `GET` | `/releases/backfill/estimate` | Estimate eligible, already-analyzed, remaining, credits, and cost for a scope. |
| `POST` | `/releases/backfill` | Queue a release backfill (`scope`, `releaseMode`, `sourceIds`, `batchSize` up to 50). |
| `PATCH` | `/recommendations/:id/review` | Set status to `accepted`, `declined`, or `done` with an optional reason. |
| `POST` | `/recommendations/:id/recheck` | Queue a recheck of one finding. |
| `DELETE` | `/recommendations/:id` | Delete a finding. |
| `POST` | `/recommendations/:id/attach-project` | Attach a finding to a project and mark it attached. |
| `GET` | `/projects/:projectId/summary` | Per-project state, counts, and top finding. |
Analysis, backfill, and recheck are asynchronous: they return `{ queued: true, jobType, message }` and run on the Knowledge Gaps worker.
## MCP Tools
Knowledge Gaps is available to agents through the [BuildBetter MCP server](../MCP/tool-reference):
* `list-knowledge-gaps` — list findings, filtered by `approvalState` (`approved` / `not_approved`), `status`, `statuses`, or `gapType`.
* `review-knowledge-gap` — approve, decline, or mark a finding done.
* `attach-knowledge-gap-to-project` — attach a finding to a tracked project.
## Troubleshooting
| Symptom | Cause and fix |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Page shows an empty feature state** | One of `success` or `knowledge_gaps` is off for the workspace. |
| **"Analyze latest releases" is disabled** | No active documentation sources, or nothing new has shipped since the last run. |
| **"Add a documentation source before running..."** | No active source resolved for the request. Add one in Success settings. |
| **No recommendations found** | Analysis has not been run yet, or every analyzed release came back `no_gap`. |
| **Estimate shows 0 remaining** | Every release in the scope has already been analyzed against the current sources. Widen the scope or change the evidence mode. |
| **Findings only ever match the changelog** | The docs source root points at a changelog rather than product documentation. Add the product docs root as its own source. |
| **"Not enough credits..."** | The run was rejected at the credit gate. Nothing was analyzed or charged. |
| **Everything comes back "Needs triage"** | Release notes are too thin. Add user-facing detail to the changelog, or switch the evidence mode to **Extracted features**. |
Run Knowledge Gaps right after Close the Loop. Close the Loop tells you which customers to tell about a release; Knowledge Gaps tells you whether there is a page to send them to.