135 lines
12 KiB
Markdown
135 lines
12 KiB
Markdown
# Search Zero-Learning Primary Entry
|
|
|
|
## Why this exists
|
|
- Search must be the default entry into Stella Ops for users who do not know Stella terminology, domain boundaries, or internal product structure.
|
|
- The current model asks the user to understand too many concepts before they can succeed: `Find/Explain/Act`, explicit scope switching, recovery actions, and a separate AdvisoryAI destination.
|
|
- Live verification also shows a real reliability gap: suggestion chips can render even when the active corpus cannot answer them. On 2026-03-07, the running AdvisoryAI service at `http://127.1.0.44` rebuilt with `documentCount=0`, `chunkCount=0`, and `doctorProjectionCount=0`, while unified overlays rebuilt with only `chunkCount=14`. Querying `database connectivity` then returned zero cards. The current UX still offered that suggestion.
|
|
|
|
## What still fails after the first pass
|
|
- The product still exposes two entry mental models: global search and a route-jumping AdvisoryAI experience. Search-originated chat actions currently navigate into `/security/triage`, which breaks page continuity and makes AdvisoryAI feel like a separate destination.
|
|
- The assistant still exposes `Find / Explain / Act` framing in chat. That pushes the user to learn the system's internal reasoning model instead of simply asking for help.
|
|
- Empty-state search still carries too much product education: domain guides, quick actions, context exposition, and explanatory labels. That is useful for experts but too loud for a self-serve default.
|
|
- Current-scope behavior is correct as a ranking concept, but the UI still talks about the mechanism instead of simply showing the best in-scope answer first and only then out-of-scope overflow.
|
|
- Suggestion reliability is fixed only when the active corpus is actually ingested. A healthy process with an empty corpus is still a bad operator experience unless the UI suppresses or fails those paths explicitly.
|
|
|
|
## What still fails after live operator use
|
|
- The product still leaves visible or hidden traces of a dual entry model. Search is supposed to be the starting point, but AdvisoryAI still feels like a separate feature instead of a secondary deep-dive opened from the search field.
|
|
- The current surface still carries internal search concepts in contracts and helpers even after the visible buttons were reduced. If `Find / Explain / Act` still changes prompt or chip behavior, the product is still teaching an internal model.
|
|
- The current history contract cannot reliably remove old failed searches after reload because the local store still accepts legacy bare-string entries with no result outcome attached.
|
|
- `Did you mean` is still visually tied to the results surface rather than the input correction moment. It needs to live immediately below the search field.
|
|
- Suggestions are still too easy to surface without enough corpus proof. Search must treat corpus readiness and suggestion executability as a product requirement, not a test-only concern.
|
|
|
|
## Product rules
|
|
1. Search is the primary entry point.
|
|
2. AdvisoryAI is a secondary deep-dive opened from search, not a competing starting point or route jump.
|
|
3. Search should infer relevance and intent; the user should not need to choose a mode or understand Stella search mechanics.
|
|
4. Search should bias to the current page context automatically; the user should not need to toggle scope.
|
|
5. Search should never advertise a suggestion that cannot execute against the active corpus.
|
|
6. Search history should contain only successful searches.
|
|
7. Telemetry remains optional. Search behavior must not depend on analytics emission.
|
|
8. Search UI must avoid teaching Stella terminology or search mechanics before the operator has even started.
|
|
9. `Did you mean` belongs directly below the search field because it is an input correction, not a downstream refinement.
|
|
10. Search should summarize close evidence automatically. AdvisoryAI expands detail; it should not be required to make the primary result understandable.
|
|
|
|
## Target interaction model
|
|
### Entry
|
|
- Keep one primary search field in the top bar.
|
|
- Add a compact AdvisoryAI launcher icon beside the search input.
|
|
- Opening chat from that icon inherits the current page, current query, and top evidence when available.
|
|
- Opening chat must stay on the current page through a global drawer or equivalent shell-level host. Search should not navigate the operator into a different feature route just to ask follow-up questions.
|
|
|
|
### Query understanding
|
|
- Infer likely user intent from the query and visible page context.
|
|
- Weight current page/domain first.
|
|
- If current-scope evidence is weak, show overflow results from outside the page scope below the in-scope section instead of asking the user to broaden scope manually.
|
|
|
|
### Result presentation
|
|
- Place `Did you mean` directly below the input because it is an input correction, not a result refinement.
|
|
- Remove explicit `Find / Explain / Act` controls.
|
|
- Remove the explicit scope toggle chip.
|
|
- Remove manual result-domain refinements from the primary flow; the server should rank the current page first and render any cross-scope overflow as a secondary section instead.
|
|
- Remove the recovery panel.
|
|
- If top results are close in score, compose one short summary across them.
|
|
- If one result is clearly dominant, present that answer first and then cards.
|
|
- Prefer concise operator-facing labels over implementation-facing labels. The UI should show "best match here" and "also relevant elsewhere", not expose ranking jargon.
|
|
|
|
### Suggestions
|
|
- Page suggestions become executable search intents, not static chips.
|
|
- A suggestion is only shown if:
|
|
- its preferred domain has live evidence, or
|
|
- the backend confirms non-zero candidate coverage for it.
|
|
- If the current corpus is empty for that page/domain, suppress those suggestion chips instead of showing dead leads.
|
|
|
|
### History
|
|
- Persist and render only searches that returned results.
|
|
- Keep history clear as a low-emphasis icon action, not a labeled call-to-action.
|
|
- Existing history entries with zero results should be ignored on load so prior failed experiments do not pollute the empty state.
|
|
|
|
## Runtime rules
|
|
### Implicit scope weighting
|
|
- Current route/domain is a ranking boost, not a hard filter.
|
|
- Visible entity keys and last action increase local relevance.
|
|
- Out-of-scope results are still allowed, but only after in-scope candidates are exhausted or materially weaker.
|
|
|
|
### Answer blending
|
|
- If top-N cards fall within a narrow score band, emit a blended summary with citations from multiple cards.
|
|
- If score separation is strong, emit a single-result grounded answer.
|
|
- The frontend should not ask the user to choose whether they want `find` or `explain`; the backend should infer the dominant answer shape.
|
|
|
|
### Suggestion viability
|
|
- Suggestions must be validated against the current corpus before rendering.
|
|
- Knowledge/domain emptiness should be detectable so the UI can suppress invalid chips.
|
|
- Empty-state contextual chips and page-owned common-question chips should preflight through the backend viability endpoint before they render.
|
|
- Live Playwright coverage must assert that every surfaced suggestion returns visible results.
|
|
- A service health check alone is not enough. On 2026-03-07, `http://127.1.0.44/health` returned `200` while the live knowledge rebuild returned `documentCount=0`; the product still surfaced dead chips. Corpus readiness is the gate, not process liveness.
|
|
|
|
## Corrective execution phases
|
|
### Phase A - Search-first and assistant-second shell behavior
|
|
- Replace route-jumping chat opens with a global assistant drawer hosted by the shell.
|
|
- Remove mode switching from the assistant UI and prompt generation.
|
|
- Make the top-bar search icon the canonical assistant entry from any page.
|
|
|
|
### Phase B - Zero-learning search surface collapse
|
|
- Remove or minimize empty-state product education that teaches Stella structure instead of solving the current question.
|
|
- Keep `Did you mean` immediately under the input and keep overflow presentation subtle.
|
|
- Keep suggestions executable, short, and page-aware without extra explanation burden.
|
|
|
|
### Phase C - Ranking, answer blending, and optional telemetry
|
|
- Refine current-page/entity/action weighting so in-scope answers dominate when sensible.
|
|
- Blend answers only when the top evidence cluster is genuinely close; otherwise show a decisive primary answer.
|
|
- Ensure analytics, feedback, and quality telemetry can be disabled without breaking search, suggestions, history, or chat handoff.
|
|
|
|
### Phase D - Live ingestion-backed reliability matrix
|
|
- Keep mock-backed E2E for deterministic UI shape.
|
|
- Add live ingested E2E for the actual suggestions and answer experience on supported domains.
|
|
- Fail fast when corpus rebuild/readiness is missing so dead suggestions are treated as setup failures, not flaky UI tests.
|
|
|
|
## Current state
|
|
- Implemented from the corrective phases: search now opens AdvisoryAI through a shell-level drawer with no route jump, restores focus back to search when the drawer closes, and removes visible assistant mode framing.
|
|
- Implemented from the corrective phases: the empty state no longer teaches Stella taxonomy through domain guides or quick links; it now keeps only current-page context, successful recent searches, and executable starter chips.
|
|
- Implemented before and during the corrective phases: explicit scope/mode/recovery controls were removed from the main search flow, implicit current-scope weighting and overflow contracts were added, and suggestion viability preflight now suppresses dead chips before render.
|
|
- Implemented before the corrective phases: the live Doctor suggestion suite now rebuilds the active corpus, fails on empty knowledge projections, iterates every surfaced suggestion, and verifies Ask-AdvisoryAI inherits the live search context.
|
|
- Implemented from the corrective phases: backend overflow is now narrow enough that clear in-scope winners suppress out-of-scope spillover, blended summaries only appear for genuinely close evidence clusters, and `SearchTelemetryEnabled` cleanly disables analytics/feedback/sink emission without affecting retrieval or history.
|
|
- Implemented from the operator-correction pass: FE search contracts no longer depend on hidden `Find / Explain / Act` metadata, starter chips wait for backend viability before rendering, `Did you mean` is the first in-panel cue under the search field, and successful recent history now uses a structured `stella-successful-searches-v3` contract that ignores legacy bare-string entries on load.
|
|
- Still pending from the corrective phases: stricter backend viability states across more domains, broader live-page matrices, and explicit client-side telemetry opt-out.
|
|
|
|
## Execution phases - operator correction pass
|
|
### Phase 1 - Search-first primary surface cleanup
|
|
- Remove the remaining FE mode concept from shared search contracts, prompt helpers, and page-owned chip selection.
|
|
- Keep one visible primary entry: search input with a compact assistant launcher beside it.
|
|
- Attach `Did you mean` directly to the input area and simplify result labels to plain operator language.
|
|
- Migrate recent history to a structured success-only format and ignore legacy failed entries on load.
|
|
|
|
### Phase 2 - Backend query understanding and suggestion hardening
|
|
- Infer answer shape from the query, route context, visible entities, and recent actions instead of any FE mode hint.
|
|
- Return stricter suggestion viability signals so FE can suppress dead suggestions when the corpus is empty, stale, or outside the current route's supported domains.
|
|
- Keep out-of-scope overflow secondary and only when it materially improves the answer.
|
|
- Keep telemetry optional and separate from retrieval, ranking, suggestion gating, and history.
|
|
- Treat clarify-only suggestion candidates as non-executable; only grounded suggestions should survive preflight into the visible chip lane.
|
|
|
|
### Phase 3 - Live ingestion-backed readiness and regression gate
|
|
- Run deterministic Playwright against the simplified surface on every change.
|
|
- Run live Playwright against ingested corpora and fail early on empty corpus, missing rebuilds, or uncompiled CLI assumptions.
|
|
- Assert that every surfaced suggestion on covered routes resolves to a non-dead-end state.
|
|
- Treat corpus readiness as part of release verification for search suggestions.
|