Skip to main content
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, 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

1

Enable the feature flags

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

Configure release sources

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

Add documentation sources

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

Run analysis

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

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

1

Select candidates

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

Check the credit allowance

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

Retrieve documentation

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

Classify

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

Persist the finding

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

​
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: 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

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=<id>). 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. 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. 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:
  • 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

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.