Skip to content

design(atlas): retrieval statistics, result feedback, and query traces — top-K survival, thumbs + essays, per-stage scores #6027

Open

Description

@dezren39

Parent: #6018 (Atlas ingestion program). Statements S21–S27 of the 2026-11-04 brief.

Requirement (Drew, in substance)

Atlas search must become measurable and judgeable, end to end:

Retrieval statistics

  1. Per file/embed: stats on what comes in from a shard on a query and makes it into the top K — shard-stage survival counts.
  2. After shard results are merged and rescored: stats on which results make the top 1, 2, 3, and the top 1–5 — final-rank distribution per file/embed. (Builds on #5774's full-vector logging per run and the #5733/#5741 rescore work.)

Feedback

  1. Simple feedback on results: "this was exactly what I needed" / "this was terrible" / everything in between.
  2. Bare minimum: thumbs up / thumbs down on all searches — every user knows how to do this with zero instruction; it must be addable from whatever surface returned the result.
  3. An optional comment may ride along; long-form feedback — up to an essay on why a result was terrible for a query — is explicitly welcomed and thanked. We normalize comments ourselves afterwards, based on context and increased detail (normalization is our job, not the user's).

Query trace

  1. Every result is associable to its query with a full trace: results carry IDs (assumed to exist — verify, and design the ID if not); for any result we can recover the scores it got at each stage (per-shard rank/score, merge, rescore stages), which shard it was in, the exact state of the embed content that was scored, and its metadata (provenance mark, version per the sibling versioning design, tier).

Uses (why this exists)

  1. Beyond performance and benchmarks, the stats + feedback guide evolutions of Atlas: what files are kept and what files aren't (feeds the versioning/retention deletion triggers), changes to our search patterns (weights, signals, expansion), and system evolution generally. Feedback data that cannot change a decision is decoration — the design names the decisions each signal feeds.

Design must answer

  • Storage shape for traces (per-query record: query id, stage scores per result id, shard, embed content hash/state, parameters used) and its own retention — traces are themselves corpus (they belong in the ingestion source set as "statistics and reports").
  • Feedback identity/weighting: whose thumbs count (Drew vs agents vs other users), per-result vs per-query feedback, and how essay comments get normalized (human pass? agent pass with the query context?) into structured signal.
  • The feedback surface per client (CLI flag, service API field, UI affordance) with the thumbs path never more than one action away.
  • Anti-gaming/quality: feedback on results the user never opened, duplicate feedback, agent self-feedback loops (agents judging their own retrievals) — named and handled.

Done looks like

A design doc: trace schema, stats aggregation model (per-embed survival + final-rank distributions), feedback capture + normalization pipeline, and the decision map (signal → retention/ranking/product decision), with implementation split into follow-ons.

Activity

  1. added
    area/infraInfrastructure, deployment, and operations
    kind/designA design proposal (design-architect): multi-step, phased, decision-bearing
    on Nov 5, 2026
  2. developing-today commented on Nov 5, 2026

    @developing-today
    Contributor
  3. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    Research hard constraint: traces are logged AT QUERY TIME, or they don't exist

    Cluster 4's one hard constraint, which this design must treat as load-bearing:

    • Per-stage scores cannot be recomputed after the corpus moves. Fan-out → merge → rescore scores depend on the exact corpus state and embed versions at query time. Any design that doesn't log at query time has no analytics — retrofitting is impossible by construction. The trace record per query: query_id, timestamp, querier context, raw query + rewritten query (the dual-submission rewriter makes these differ), corpus snapshot ids (per-shard head markers), and per candidate: embed id + embed version id, shard, per-stage (score, rank) at fan-out/merge/rescore, final rank, and which K cutoffs it survived. Ranks must be logged for the full candidate list at each stage, not just final top-K — survival at K=3 is only computable if stage outputs were recorded deeper than 3. Top-K survival stats (K=1/2/3/5 by shard, tier, source type) are then funnel aggregation over this log, not a separate system.
    • Feedback binding is (query_id, result_id, embed_version_id) — feedback against a version, or retention/versioning changes make old feedback uninterpretable.
    • Thumbs are sparse and negatively biased — pair them with implicit signals (copy ≈ success, requery/regenerate ≈ failure, dwell) from day one; neither raw thumbs nor implicit counts are auto-reranking inputs at personal scale (position bias). Their highest-value use: negative-feedback queries are promoted into a versioned golden set with corrected ground truth, and the golden set gates chunking/rescore/model changes. Free-text essays normalize via an LLM judge with an explicit rubric (labels like wrong-source / stale-version / right-doc-wrong-span / missing-doc / ranking-only), calibrated by periodic hand-scored samples — an uncalibrated judge drifts silently.

    Wave-2 children filed under this issue

    • #6046 — feedback-derived eval set gating index changes
    • #6047 — clicks/copies/dwell/requery as weak labels

    — Wave-2 research fold-in, 2026-11-04 (prior-art doc: ~/workspace/scratch/atlas-ingestion-brief-2026-11-04/prior-art-research.md)

  4. added
    queue/queuedHas a queued task in the Supabase agent queue
    task/triageQueue packet kind: verify, reproduce, and route this item
    on Nov 5, 2026
  5. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  6. added
    work/assignedQueue worker lifecycle state
    queue/claimedQueue worker lifecycle state
    and removed
    queue/queuedHas a queued task in the Supabase agent queue
    on Nov 5, 2026
  7. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  8. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    Agent note - handed off

  9. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  10. 48 remaining items

  11. dezren39 commented on Nov 6, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  12. dezren39 commented on Nov 6, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  13. dezren39 commented on Nov 6, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · handed off

  14. added
    queue/claimedQueue worker lifecycle state
    and removed
    status/parkedDeliberately paused with a recorded resume condition
    queue/parkedQueue task is parked (waiting on CI, time, or an event)
    on Nov 6, 2026
  15. dezren39 commented on Nov 6, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · picked up

  16. dezren39 commented on Nov 6, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · triaged

    Triage / route

    No follow-up queue task was added because the parent design and the two relevant children already exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area/infraInfrastructure, deployment, and operationskind/designA design proposal (design-architect): multi-step, phased, decision-bearingtask/triageQueue packet kind: verify, reproduce, and route this item

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions