Ghost Team Brain

discoverability-framework

6 min read

✏️ Edit this page on GitHub

Discoverability framework (the 4 R’s + the loop)

The product-defining model: the four R’s are the measurements; the loop is the workflow on top; the UI is how a customer runs it. Score mechanics (the four 25-pt buckets) live in ado-score-model — this page is the durable framing + the UI decision. The customer-facing artifacts (the flywheel diagram + dashboard mock) are MADE, not stored here — see Source.

Current truth

  • The four R’s (external, public-facing framework — deeper than “tools”). A methodology you understand once you’re in the product; each maps to one of the four locked score buckets (ado-score-model):
    • Reachability — your app works, is healthy, and is in the right registries/places.
    • Relevance — the right description + keywords, optimized for agents (and likely humans later) to find you.
    • Retrievability — the agent knows you’re a candidate, by whatever mechanism (for Claude: the MCP-registry keyword tool-search; but also training-data awareness and direct connectors — both put you in the candidate pool). Defined mechanism-agnostically (refined 2026-06-26) so the bucket survives any host / future routing — the outcome is “the LLM knows you exist as a candidate,” not the specific retrieval path. (the long-list stage; formerly called “Recall” internally.) In Claude’s two-stage path, retrievability = the long list (keyword search → registry) and rank = the short list (the model’s pick).
    • Rank — you’re picked over rivals.
    • Rank has two decoded surfaces that behave OPPOSITELY on the edit lever (2026-07-06): the in-conversation rank (registry search + picker) responds causally to metadata edits (≈3 ranks/keyword; 88%-directional edit advisor → claude-registry-search-decoded), while the browsable directory rank is freshness-driven (launch boost + a fixed 14-day “New” badge) and metadata edits are refuted as a lever there → claude-directory-rank-decoded. Fixes/advice must always name which rank surface it targets — promising directory-rank gains from copy edits is not supported.
    • Each R should get a public definition / a “Four R’s of Discoverability” blog post so it reads as a researched framework, not a made-up one. Tagline: “find you, use you, and keep coming back.”
    • Client-narrative simplification (2026-06-26): for the operator deck the value chain is presented as Retrievability → Rank — come with an intent → does an external tool get selected? → are you a candidate (Retrievability) → are you picked (Rank)? Relevance folds in as a signal feeding Retrievability/relevance rather than a separate headline stage; training-data awareness + direct connectors are narrated under Retrievability (candidate pool). This is a presentation layer on top of the locked four-R model, not a change to it. “Recall” vs “Retrievability” naming settled on Retrievability (2026-07-01; Elliot leaned Retrievability, “Recall” had been used only for brevity).
  • The loop sits ON TOP of the R’s (they don’t fully overlap — the R’s are measurements, the loop is the optimization workflow): Measure → Score → Fix → Lift.
    • “Optimize” placeholder renamed → “Fixes” (clearer; “optimize” is vague).
    • “Lift” kept (debated — Elliot read it as an outcome not an action; resolution: keep it for the optimization-cycle / marketing feel, give it the description “submit your improved app,” visualize as an upward cycle). “Ship” rejected (engineer-only term); “resubmit” alone too flat.
    • Internally the loop keeps finer steps (MetaTuner-style monitor / decode between Score and Fix): Score ≈ score + monitor; Fix ≈ decode (why is selection happening/blocked) + make the change. The decode engine — how we actually explain a selection (run artifacts, model reasoning, direct model interrogation) — is discovery-analysis-method. Keep the internal version even though the public loop is the 4 boxes.
  • Two discovery surfaces — the loop runs consistently across both:
    • Organic discovery — the connection picker, initial users. Current focus.
    • Connected discovery — once a user has connected you, do you still appear for relevant prompts? Requires simulating which other apps a user has connected, then testing appearance. Flagged as an enterprise-plan feature (roadmap, not now). Also in scope over time: the full customer journey (click-through to website) and memory profiles (business vs consumer users).
  • Product UI structure (decided 2026-06-23). The score is the central cockpit on entry. Tabs:
    • Prompts — set/manage your target prompts; AI-suggested intents (from real logs); topic groupings (see how you do across topics — like AEO platforms e.g. AppTweak).
    • Discoverability — the live view of how you appear for your prompts: rank table + share of visibility, with click-in evidence (“why”). (Replaces a standalone “Competitors” tab — that view folds in here.)
    • Fixes — the recommendation engine: evidence-based suggested changes. Placeholder / “coming soon” for v1.
    • Usage / Analytics — server logs, connector popularity. Grayed, not v1 (needs our own SDK/tag or host hosting).
    • Registry — keyword/registry optimization surface. Rebuild later as a paid feature (don’t expose the secret sauce yet).
    • The recommendation engine (Fixes) is a separate, future workstream that must be intelligent enough to prioritize across organic, connected, and tool-level signals (limited tools/credits) — see direct-booker.

Open questions

  • Connected-discovery: how exactly to simulate a user’s connected environment and test appearance.
  • Recommendation-engine design — the “how do we decide what to change, and why” doc (the Direct Booker workstream).
  • External name still open (discipline/score naming) — see ado-score-model Open questions.

Source

  • Customer-facing artifacts (MADE, pointers only): the flywheel diagram + write-up docs/drafts/ado-loop-architecture.md and the dashboard mock docs/drafts/dashboard-overview-mock.html in the product repo (vincentmcleese/discoverability-platform).

Timeline

  • [2026-07-07] (maintenance) Added the rank-surface split: in-conversation rank (edits work, causal) vs browsable-directory rank (freshness-driven, edits refuted) — both now decoded; the framework previously had no slot for the directory-browse surface, so the Fixes-relevant refutation had no home.
  • [2026-06-26] (internal deck-review — Vincent + Elliot, recorded by Elliot) Sharpened Retrievability to a mechanism-agnostic “the LLM knows you’re a candidate” (registry tool-search or training-data awareness or direct connection all feed the candidate pool) so the bucket survives any host / future routing; mapped Claude’s two stages as retrievability = long list (keyword→registry) / rank = short list (model pick). For the Direct Booker client narrative, collapsed the value chain to Retrievability → Rank (Relevance folds in) — a presentation layer on top of the locked four-R model. “Recall” vs “Retrievability” naming still open (later settled on Retrievability, 2026-07-01). Grounded in direct-booker.
  • [2026-06-23] (call — Vincent + Elliot, recorded by Vincent) Framework locked: the four R’s confirmed as the public framing + the Measure → Score → Fix → Lift loop on top (“Optimize”→“Fixes”; “Lift” = “submit your improved app”). Split organic vs connected discovery (connected = enterprise feature). Decided the product UI structure (score cockpit + Prompts / Discoverability / Fixes / Usage / Registry, with Fixes + Usage grayed for v1). Agreed each R needs a public definition (blog post). Score-specific + category decisions from the same call → ado-score-model; Direct Booker recommendation-engine workstream → direct-booker.

Graph View

Backlinks