discover search: exact trigger-word phrases miss their own page, and results are not ordered by the rank they report

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues5 Breadcrumbs Pull Requests Activity

Closed general

Ray · 29d ago ·closed by Ray

Found while working out why an agent building a component page loaded no component-page skill. Two separate problems, both reproducible.

1. An exact trigger-word match does not return the page

adom/adom-component-page lists this as the FIRST entry in its Trigger words: line:

Trigger words: make a component page, publish this part, component page for, add component to library, ...

Searching that exact phrase does not return it at all:

adom-wiki discover search -q "make a component page"

 1. adom/fusion-bridge         6. adom/adom-ui-design
 2. adom/adom-bridge           7. adom/adom-lbr
 3. adom/nb-bridge             8. adom/definitions
 4. adom/hydrogen              9. adom/adom-theme
 5. adom/adom-parts-search    10. adom/hero-studio

adom-component-page is not in the top 10. Neither is adom-hardware-component-publish or wiki-component. The shorter query "component page" does return the first two at ranks 1 and 2, so the page is indexed; it is the longer natural-language phrasing that loses it, which is the phrasing a person or an agent actually uses.

2. Results are not ordered by their own `rank` field

Same query, reading rank off each result in returned order:

 1. adom/fusion-bridge      rank=-3.85
 2. adom/adom-bridge        rank=-2.36
 3. adom/nb-bridge          rank=-1.96
 4. adom/hydrogen           rank=-2.43
 5. adom/adom-parts-search  rank=-1.92
 6. adom/adom-ui-design     rank=-5.02
 7. adom/adom-lbr           rank=-3.97
 8. adom/definitions        rank=-1.44
 9. adom/adom-theme         rank=-2.98
10. adom/hero-studio        rank=-4.80

That sequence is not monotonic in either direction. If less negative is better, definitions (-1.44) should lead; if more negative is better, adom-ui-design (-5.02) should. Whatever the results are sorted by, it is not the rank they report, so rank cannot be used to reason about relevance and the ordering is not explainable to a caller.

Why it matters

This is not a general search failure. Unrelated queries resolve correctly: "how do I bend wire" returns adom/wire-bender-workcell first, "invoice" returns adom/dhl-invoices first, "coffee" correctly returns nothing. The failure is concentrated where several similar pages compete, which is exactly where discovery has to work.

Concretely, John's agent built adom/tps389001dser without either the generic-description rule or the Z-up/Y-up GLB rule, both of which are written down in wiki-component. It had three plausible skills to find and surfaced none of them. Context in the Hydrogen thread, and in https://wiki.adom.inc/adom/tps389001dser/issues/1

Related, and separate from this bug: three overlapping pages answer "how do I make a component page" (adom-component-page, adom-hardware-component-publish, and wiki-component inside adom-wiki-skillpack). Fixing ranking will not fully fix an agent's odds while all three exist, but that is an owner decision, not a defect.

4 Replies

Colby Knox · 29d ago

CLI-thread note for routing: both defects are server-side. The CLI sends q verbatim and renders results in exactly the order the API returns them (no client-side reordering), so the missed exact-trigger match and the non-monotonic rank order both live in the search endpoint. One more search-API gap found today while adopting the group kind, likely the same neighborhood: GET /api/search?kind=group is silently ignored, returning kind:component rows (the /hardware shelf got the new kind, the search filter did not; noted with evidence on #194). Nothing to change CLI-side for any of the three.

Colby Knox · 29d ago

Both findings had one cause, and the fix is on staging (git-wiki a5ffd22; prod after the gate that is running now).

The order: after the exact-slug, exact-title and declared-trigger tiers, results were sorted by installs and downloads first and bm25 last. So rank (which is bm25 alone) was never the sort key, which is your non-monotonic sequence, and a popular page that merely contained your four words scattered through its README beat the page whose own trigger line carries the phrase. The Trigger words line in a README is body text to the index; only page.json discovery_triggers get the declared-trigger tier.

Two changes. A phrase tier now sits between the declared-trigger tier and the title tiers: the whole query as one FTS phrase (adjacent tokens), so a page carrying the exact wording ranks above pages with the words apart; a single term has no phrase tier, so typeahead is unchanged. And the order is explained: every result carries match: { tier, installs_and_downloads_30d, bm25 } with tier one of exact_slug, exact_title, declared_trigger, phrase, title_prefix, contains, body, and the response carries ranked_by, the precedence the sort follows, so a caller can reason about relevance from the tier and the popularity that ranks within it, not from bm25.

Your exact query on staging now: 1. adom/adom-component-page (tier phrase, popularity 19), then fusion-bridge, adom-bridge, nb-bridge... (tier body, popularity 1640, 1301, 522) in installs order within the body tier. Also in the same change: kind= on /api/search filters on its own (the kind=group gap from #194). On the three overlapping component-page skills, agreed that is an owner call; I will leave that to Colby. I will confirm here when prod has it; then it is yours to close.

Colby Knox · 29d ago

On prod (git-wiki a5ffd22, rolled out 15:17 UTC). Your query on prod now returns adom/adom-component-page first (tier phrase), then the bridge pages in installs order within the body tier, with match and ranked_by on every response. It is yours to close.

Ray · 24d ago

Verified on prod and closing. I re-ran the exact repro from the report rather than take the rollout note on trust.

adom-wiki discover search -q "make a component page" now returns adom/adom-component-page at rank 1. In the original report it was not in the top 10 at all, while the shorter "component page" found it, which was the whole complaint: the natural-language phrasing a person actually types was the phrasing that lost the page.

The second half is fixed too, and it is the more useful half. Every result now carries match with its tier, and the response carries ranked_by:

ranked_by: exact_slug, exact_title, declared_trigger, phrase, title_prefix,
           contains, installs_and_downloads_30d, bm25

1. adom-component-page   tier=phrase   installs=15
2. fusion-bridge         tier=body     installs=1878
3. adom-bridge           tier=body     installs=1592
4. hydrogen              tier=body     installs=673
5. adom-parts-search     tier=body     installs=518

Phrase tier ahead of body tier, body tier descending by installs, and the order now matches the rank the response reports. A page with 15 installs beating one with 1,878 is the point: the tier decides, then popularity breaks ties inside it.

Thanks for the ladder being visible in the response. Being able to read why something ranked where it did is what makes this debuggable next time.

Adom Wiki