The refund-window story from the first post in this series landed because it was specific. One page, one outdated sentence, one confident AI answer pointing a customer at a policy that hadn't existed in eighteen months. The support team traced the hallucination in an afternoon. The page had been right, then wrong, then forgotten, and the retriever never knew the difference.

It wasn't an edge case. Every docs-plus-AI stack we've audited has five of them sitting in plain sight. Here are five more, anonymized but exact.

Retrieval failures are not a mystery. They cluster into a small number of repeatable shapes, and once you know the shapes you can find them in your own docs in under a day. What follows is a catalog of the ones we pull out of nearly every engagement: what they look like, why the model can't tell, and the structural fix for each.

Failure 1: The deprecated endpoint that still ranks#

An API reference still lists /v1/customers/search as current. The page carries a small "Deprecated — use /v2" banner at the top, styled as a yellow callout with an icon. Visually obvious to a human. To the retriever, it's a sentence in the DOM like any other, often stripped entirely by the Markdown converter feeding the embedding pipeline.

The assistant returns the v1 endpoint in a code sample. A customer ships it. The endpoint keeps returning data for three more weeks, then a 410, then a Slack thread.

The page ranks because term match still rewards it. "Search Customers" scores higher than "Migrate From v1" for the query how do I search customers, and most hybrid retrievers weight BM25 heavily enough that a keyword-dense legacy page beats a semantically relevant migration guide. Deprecation lives in the chrome of the page — the banner, the badge, the sidebar label — and none of that chrome survives the trip into a vector index.

The fix is to treat deprecation as a property, not a decoration. Put it in frontmatter the retriever can read, and echo it in the first sentence of the body:

---
status: deprecated
deprecated_in: 2024-11
replacement: /api/v2/customers/search
sunset: 2025-06-01
---

Then the first line of the page: This endpoint is deprecated. Use /v2/customers/search. Better still, when the replacement is stable, delete the old reference page and 301 the URL. A page that does not exist cannot be retrieved. A page whose first sentence announces its own obsolescence at least gives the model a fighting chance to disclaim the answer.

Failure 2: The regional policy leaking into global answers#

A SaaS product treats data residency differently for EU customers under GDPR. There's a page titled "Data Residency" that describes the EU rules in detail. The word "EU" appears twice in the body, two paragraphs down. It does not appear in the title, the H1, the URL slug, or any heading on the page.

An Australian admin asks the assistant where their tenant's data is stored. The assistant retrieves the residency page — it's the only document with the phrase "data residency" — summarizes it confidently, and tells the customer their data lives in Frankfurt. It does not live in Frankfurt. It lives in Sydney. The assistant has now created a compliance incident out of a documentation gap.

Scope was implicit. A human reader scans the URL, the breadcrumb, the regional dropdown at the top of the portal, the flag icon next to the heading. The retriever sees none of that. It sees a chunk of text that matches the query and a confidence score, and it hands both to the generator.

The fix is to put scope in the title and the slug. "Data Residency (EU)" and "Data Residency (APAC)" are two pages, not one page with two sections. If the product is genuinely global with regional variants, every page that describes regional behavior should carry the region in its title, its frontmatter, and ideally its first sentence. Retrieval quality is a function of how much scope the first 200 tokens of a chunk carry, and the first 200 tokens of "Data Residency" do not carry enough.

Failure 3: The tutorial step that assumes a feature flag#

A getting-started tutorial reads, in step four, "Now enable webhooks in the dashboard and paste the URL from step three." Two years ago, webhooks sat behind a feature flag that support had to flip by request. That sentence used to follow a paragraph explaining the flag and how to request access. Somebody cleaned up the page during a redesign. The dependency got lost in the diff.

A new user follows the tutorial. The webhook screen returns a 404 because their workspace was provisioned after the flag became opt-in but before it became default. They ask the assistant. The assistant, asked about a 404 on the webhook setup screen, helpfully repeats the tutorial step, because the tutorial is the highest-ranking page for "webhook setup."

Implicit prerequisites break under retrieval the same way implicit scope does. The page used to carry context in the prose around it. The refactor removed the prose and kept the step. No embedding model recovers a prerequisite that isn't on the page anymore.

The fix is to surface prerequisites as structured data, consumed by the retriever as context rather than buried in a paragraph that might get edited out in the next pass:

---
requires:
  - feature: webhooks_enabled
    check: Settings > Integrations > Webhooks is visible
  - plan: pro_or_above
---

The retrieval layer can then inject requirements into the context window alongside the matched chunk, and the generator has something to condition on besides the four sentences that happened to match. It also gives the docs team a linter target: any page whose requires field lists a feature that no longer exists is a page to audit.

Failure 4: The conflicting pricing page#

Pricing lives in two places. The public pricing page is owned by marketing, rendered from a CMS, and optimized for conversion. The billing documentation is owned by the docs team, rendered from the same repo as the rest of the docs, and optimized for accuracy. They drift. The marketing page says "$0.002 per request after the first million." The billing docs, updated after the last pricing revision, say "$0.0018." Both are indexed. Both rank for how much does this cost per request.

The assistant retrieves whichever one wins the ranking coin flip for that session. Both look authoritative. Neither cites the other. A prospect in a sales call gets one number; a developer reading the docs gets another; the account executive finds out about it on a Zoom with a confused customer.

Two sources of truth for the same fact is not a retrieval bug. It's an information-architecture bug that retrieval exposes. Humans reading both pages would notice the mismatch and ask. A retriever treats them as independent documents with independent relevance scores.

The fix is single-source. One page owns the fact. Every other page that references it pulls the value by transclusion, from a shared data file or a headless CMS field, never by re-typing. In a docs-as-code stack this often looks like a YAML file of canonical values and a build-time include:

# _data/pricing.yml
api_requests:
  included: 1_000_000
  overage_usd: 0.0018
  effective: 2026-01-15

The marketing site and the docs both render from the same key. When the number changes, it changes once. The retriever cannot index contradictory values because contradictory values cannot exist. This is also the pattern that keeps AI answers about pricing, rate limits, SLA tiers, and regional availability from drifting the week after a pricing update ships.

Failure 5: The answer that requires three pages#

"How do I rotate an API key without downtime?" The actual procedure requires reading the key-management page (how to generate a new key), the overlap-window page (how long old and new keys can coexist), and a note buried in the migration guide about which header name the client libraries prefer during rotation. No single page contains the full procedure. A human reader would piece it together, probably via a support thread. The retriever fetches the top-ranked page and stops. Most production RAG configurations pull three to five chunks; even with generous top-k, the retriever tends to pull three chunks from the same page rather than one chunk each from three pages, because lexical and semantic similarity both reward within-page consistency.

The answer lives in the joins, not the nodes. Your docs have a graph structure that a senior engineer has internalized and a new hire has not. The retriever is a new hire.

The fix is task-oriented pages built around real user intents, not around the product's internal object model. "Rotate an API key without downtime" deserves its own page, composed of the facts from all three source pages, even if that means repeating a sentence about header preference. Duplication is cheaper than the alternative, which is an assistant that answers two-thirds of a multi-step procedure and lets the customer discover the missing third in production. The test is simple: for every top-20 support query, is there one page whose title is the query? If not, that's the page to write next.

The pattern behind the patterns#

Every one of these failures has the same shape. The docs were written for a human reader who brings context, scans for scope, disambiguates across pages, and notices when a banner contradicts a paragraph. Retrieval brings none of that. It brings string similarity and a confidence score.

The common fix is the same across all five: move the information a human reader would extract from page structure, visual chrome, URL paths, and site navigation into the text and frontmatter of the page itself. Make status explicit. Make scope explicit. Make prerequisites explicit. Make sources of truth explicit. Make tasks explicit. Anything implicit gets eaten by the retriever.

This is why we push clients toward a structured-content model before touching the RAG stack. You can buy a better embedding model. You cannot buy your way out of a doc set that encodes half its meaning in sidebar labels.

Closing#

If any of these sound like a page you own, it probably is. None of them are rare. All of them are cheap to fix once you know what you're looking for — a morning of frontmatter, an afternoon of consolidating duplicates, a week of writing task pages for the top support queries. The fix is not an AI problem. It's a structure problem, and structure is the part of the stack the docs team already owns.

If you want help finding yours, that's what we do. Send us your top ten support tickets from last quarter and we'll tell you which of the five you have.