frame find() as a ranked top-3 shortlist (routing hint, not oracle) + confidence flags

54459a9b15aba85c006d517ed03ab7643870ce73 · 2026-08-01 22:49:00 -0700 · Steve

Shared _shortlist() formatter for both find branches; warns on weak (<0.15) or close (<0.05 margin) picks. Honest product shape given held-out top-1 is imperfect. Ship ② per Steve.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Files touched

M cabinet_directory.py

Diff

commit 54459a9b15aba85c006d517ed03ab7643870ce73
Author: Steve <steve@designerwallcoverings.com>
Date:   Sat Aug 1 22:49:00 2026 -0700

    frame find() as a ranked top-3 shortlist (routing hint, not oracle) + confidence flags
    
    Shared _shortlist() formatter for both find branches; warns on weak (<0.15) or close (<0.05 margin) picks. Honest product shape given held-out top-1 is imperfect. Ship ② per Steve.
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 cabinet_directory.py | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/cabinet_directory.py b/cabinet_directory.py
index 20e010b..b382cd7 100644
--- a/cabinet_directory.py
+++ b/cabinet_directory.py
@@ -109,6 +109,30 @@ def find(query: str, top: int = 3):
     return scored[:top]
 
 
+def _shortlist(query: str, ranked, note: str = "") -> str:
+    """Present find() results as a ranked SHORTLIST (a routing hint, not an oracle).
+
+    Routing here is a lexical-semantic score over 12 short officer docs — good enough to
+    narrow to a few candidates, NOT to trust blindly as a single answer (held-out top-1
+    ~40-75%; see eval_find.py). So we always show up to 3 and flag weak/ambiguous picks.
+    """
+    if not ranked:
+        return f"no officer matched {query!r}. Try 'list' to see all officers."
+    s1 = ranked[0][1]
+    s2 = ranked[1][1] if len(ranked) > 1 else 0.0
+    lines = []
+    if note:
+        lines.append(note)
+    lines.append(f"top {len(ranked)} officer(s) for {query!r} — ranked shortlist, pick the best fit:")
+    for i, (o, score, hits) in enumerate(ranked, 1):
+        lines.append(f"  {i}. {o['vp']} (score {score:.3f}; matched: {', '.join(hits) or '—'})")
+    if s1 < 0.15:
+        lines.append("  ⚠ low confidence — verify the pick or rephrase (this is a hint, not a decision).")
+    elif s1 - s2 < 0.05:
+        lines.append("  ⚠ top picks are close — could be any of the above; use judgment.")
+    return "\n".join(lines)
+
+
 def handle(text: str) -> str:
     cmd = (text or "").strip()
     low = cmd.lower()
@@ -136,20 +160,11 @@ def handle(text: str) -> str:
         q = cmd[4:].strip()
         if not q:
             return "usage: find <task or keywords>"
-        ranked = find(q)
-        if not ranked:
-            return f"no officer matched {q!r}. Try 'list' to see all."
-        lines = [f"best officer(s) for {q!r}:"]
-        for o, score, hits in ranked:
-            lines.append(f"  → {o['vp']} (score {score:.3f}; matched: {', '.join(hits) or '—'})")
-        return "\n".join(lines)
+        return _shortlist(q, find(q))
     # bare query with no verb → treat as find
     ranked = find(cmd)
     if ranked:
-        lines = [f"(interpreted as find {cmd!r})"]
-        for o, score, hits in ranked:
-            lines.append(f"  → {o['vp']} (score {score:.3f}; matched: {', '.join(hits) or '—'})")
-        return "\n".join(lines)
+        return _shortlist(cmd, ranked, note=f"(interpreted as find {cmd!r})")
     return f"unknown command {cmd!r} — try 'help'"

← ac91d16 scorer fix (field-weight + trigram-downweight + synonyms) + · back to A2a Lab · chore: lint (ruff, 7 autofixed), refactor self-review, v1.0. 2a64bf9 →