102 lines
8.0 KiB
Markdown
102 lines
8.0 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.
|
|
|
|
## 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.
|
|
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.
|
|
|
|
## 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 before 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.
|
|
- Still pending from the corrective phases: shell-level assistant unification, assistant de-mode-ing, empty-state collapse, broader live-page matrices, and explicit client-side telemetry opt-out.
|