Skip to content

Escalation & Fix Acceptance

The four-part escalation flag

Every ESCALATE carries exactly four pieces:

  1. The dimension — which of the five.
  2. The specific blocker — the concrete reason the operator cannot resolve it (e.g., "no Wikidata entry exists; creating one requires meeting notability criteria and external submission" — not "needs more info").
  3. What an agent observes instead — the consequence in production (e.g., "an AI agent cannot cross-reference the brand to an authoritative source, so it cites the page with low confidence or omits it").
  4. The exact action that unblocks it — the specific real-world step (e.g., "claim the Google Business Profile at business.google.com and add its URL to the sameAs array I drafted").

Example: Wikidata escalation

  • Dimension: Entity Authority (Dimension 5)
  • Specific blocker: No Wikidata entry exists. Creating one requires meeting notability criteria and external submission.
  • What an agent observes instead: The brand is not linked into the entity graph AI models use to cross-reference, so it is cited with hedged language or omitted.
  • Exact action that unblocks it: Create a Wikidata item using the facts in /llms-full.txt, then add the resulting https://www.wikidata.org/wiki/Q… URL to the sameAs array.

The fix-acceptance gate

Every generated artifact must pass this self-review:

Universal checks (every fix)

  • [ ] Moves the score. The fix targets the specific sub-criterion that lost points in the rubric. If it doesn't raise the dimension's score, it is not a fix — drop it.
  • [ ] Specific, not generic. If the artifact could be pasted into any website unchanged, it is not finished. It must reference this page's real entity, claims, or URLs.
  • [ ] Self-contained. The artifact is complete and deployable as-is — no "fill in your X" gaps left for the user except where a value is genuinely unknowable from the page (then ESCALATE that value, don't placeholder it).

Dimension-specific checks

  • JSON-LD fixes: Valid JSON (parses), valid Schema.org types and property names, entity type matches what the page actually is, @context is https://schema.org, required properties present, no invented facts.
  • /llms.txt and /llms-full.txt: Placement instruction included (agent-discovery links go at the TOP of <body>, never footer), llms-full.txt contains facts, not just URLs.
  • robots.txt / crawl fixes: Does not block GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, or Googlebot; OAI-SearchBot and GPTBot treated as distinct crawlers.
  • Content rewrite fixes: Leads with a specific, verifiable claim — not a tagline; preserves the page's factual meaning; dates use <time datetime="ISO-8601">.

Fail handling

If a fix cannot pass its checks because a required fact is unknowable from the page, do not ship a guess. Convert it to an ESCALATE entry naming the exact missing value and where to get it.

The audit-tool gap stance

HTML→markdown fetch tools strip <script type="application/ld+json">, making schema-rich pages appear schema-free. A low score from a stripped read is unverifiable, not a confirmed gap.

Never fabricate duplicate schema to paper over a stripped read. Instead: 1. Check /llms.txt and /llms-full.txt — agent-native endpoints that survive markdown conversion 2. Attempt to read the raw page source 3. If raw source is unavailable, treat any low read as unverifiable — set a floor score and flag it 4. ESCALATE the verification step with "provide raw page source or run Google Rich Results Test" as the unblocking action

A fix that can't be verified is an escalation, not a guess.