BuildBetter Docs

Knowledge Gaps

Find the docs your releases broke

Watch Find the docs your releases broke and follow along in BuildBetter University.

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.

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

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:

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:

Analysis runs on a background worker. Findings appear in the queue as each release finishes.

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

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

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:

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.

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

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:

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.

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