66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# Search Self-Serve Contract
|
|
|
|
## Purpose
|
|
- Define the page-owned contract for answer-first search.
|
|
- Ensure every high-value page can expose common operator questions and clarifying prompts without editing `GlobalSearchComponent`.
|
|
- Keep the self-serve experience deterministic, evidence-first, and testable.
|
|
|
|
## Rule (mandatory for page teams)
|
|
- Every page that wants answer-first self-serve behavior must declare `selfServe` metadata in `SEARCH_CONTEXT_DEFINITIONS`.
|
|
- Page components should continue to implement `SearchContextComponent` so ownership remains explicit.
|
|
- `selfServe` definitions must provide one or both of:
|
|
- `commonQuestions[]`
|
|
- `clarifyingQuestions[]`
|
|
- Question entries must provide:
|
|
- `key` / `fallback` for the executable question text
|
|
- optional `kind` (`page`, `clarify`, `recent`)
|
|
- optional `preferredModes` (`find`, `explain`, `act`)
|
|
- Question arrays must stay deterministic and bounded:
|
|
- at most 3 base common questions per page
|
|
- at most 2 base clarifying questions per page
|
|
- concise, operator-facing wording
|
|
- no tenant secrets or volatile IDs in fallback copy
|
|
|
|
## Answer-first UX contract
|
|
- Every non-empty search must render one visible answer state before raw results:
|
|
- `grounded`
|
|
- `clarify`
|
|
- `insufficient`
|
|
- `grounded` states must expose visible evidence summary plus citations or top-result references.
|
|
- `clarify` states must offer narrowing questions instead of a blank panel.
|
|
- `insufficient` states must explain the lack of grounding and still provide credible next questions or next searches.
|
|
|
|
## Runtime behavior
|
|
- Empty-state search uses `commonQuestions[]` for page-owned "Common questions".
|
|
- The active mode (`Find`, `Explain`, `Act`) reorders questions via `preferredModes`.
|
|
- A recent-action question may be prepended from the latest meaningful page action:
|
|
- `Find` -> related discovery question
|
|
- `Explain` -> why-it-matters question
|
|
- `Act` -> what-to-do-next question
|
|
- Result-state answer panels use:
|
|
- `commonQuestions[]` as follow-up questions when grounded evidence exists
|
|
- `clarifyingQuestions[]` when no grounded answer exists
|
|
- "Search next" remains driven by contextual chip logic so pages do not need to define a second parallel action system.
|
|
|
|
## Source of truth
|
|
- Page registry and interfaces:
|
|
- `src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts`
|
|
- Runtime composition:
|
|
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
|
|
- Search surface:
|
|
- `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
|
|
|
|
## Testing requirements
|
|
1. Add unit coverage for route-specific questions in `ambient-context.service.spec.ts`.
|
|
2. Add unit coverage for answer-state rendering in `global-search.component.spec.ts`.
|
|
3. Add Playwright coverage for:
|
|
- grounded answer
|
|
- clarify recovery
|
|
- answer-to-AdvisoryAI handoff
|
|
4. Keep route and API behavior mocked/deterministic; no live network dependencies.
|
|
|
|
## Relationship to chip contract
|
|
- `search-chip-context-contract.md` still governs contextual chips and route-suggestion behavior.
|
|
- This document governs answer-first questions and fallback states.
|
|
- Page teams adding self-serve behavior usually need to update both contracts together.
|