97 lines
5.6 KiB
Markdown
97 lines
5.6 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`)
|
|
- 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
|
|
|
|
## Priority rollout ownership
|
|
| Context ID | Route family | Page ownership rule | Verification floor |
|
|
| --- | --- | --- | --- |
|
|
| `findings` | `/security/triage`, `/security/findings` | Security triage pages own the findings questions and clarifiers. | Mocked Playwright journey + shared search regressions |
|
|
| `policy` | `/ops/policy` | Policy workspace owns the questions and recovery prompts for rules, gates, and exceptions. | Mocked Playwright journey + shared search regressions |
|
|
| `doctor` | `/ops/operations/doctor`, `/ops/operations/system-health` | Doctor pages own the health-check questions and release-readiness follow-ups. | Mocked Playwright journey + live Doctor route pack |
|
|
| `timeline` | `/ops/timeline`, `/audit`, `/evidence/audit-log` | Timeline/Audit pages own time-window clarifiers and causal follow-ups. | Mocked Playwright journey |
|
|
| `releases` | `/releases`, `/mission-control` | Release-control pages own approval/blocker/next-step questions. | Mocked Playwright journey |
|
|
|
|
## Page team checklist
|
|
1. Add or update the route entry in `SEARCH_CONTEXT_DEFINITIONS`.
|
|
2. Define bounded `commonQuestions[]` and `clarifyingQuestions[]`.
|
|
3. Keep copy operator-facing; do not expose Stella internals or scoring jargon.
|
|
4. Verify the page still works with telemetry disabled or OTLP unset.
|
|
5. Add/update unit coverage for route-specific questions and a Playwright journey for the page family.
|
|
|
|
## 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 guidance 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".
|
|
- A recent-action question may be prepended from the latest meaningful page action:
|
|
- opened/used result -> why-it-matters question
|
|
- search/chat expansion -> what-to-verify-next question
|
|
- fallback -> related follow-up question
|
|
- Result-state answer panels use:
|
|
- `commonQuestions[]` as follow-up questions when grounded evidence exists
|
|
- `clarifyingQuestions[]` as non-executable narrowing guidance when no grounded answer exists
|
|
- "Related searches" remains driven by contextual chip logic so pages do not need to define a second parallel action system.
|
|
|
|
## Optional telemetry hooks
|
|
- Search may emit optional client-side telemetry markers for backlog triage:
|
|
- `search_self_serve_gap`
|
|
- `search_self_serve_reformulation`
|
|
- `search_self_serve_recovery`
|
|
- `search_self_serve_suggestion_suppressed`
|
|
- These markers are additive only. If telemetry is disabled or the sink is unavailable, search behavior, history, and assistant handoffs must remain unchanged.
|
|
- Marker payloads must avoid raw query text. Use route, answer state, counts, and reformulation depth instead.
|
|
|
|
## Gap review workflow
|
|
1. Review repeated `search_self_serve_gap` and `search_self_serve_reformulation` events by route family.
|
|
2. Compare them with visible no-result/clarify journeys from Playwright and operator feedback.
|
|
3. Update the page-owned question set or starter chips for the affected route.
|
|
4. Add or tighten a Playwright journey before marking the gap closed.
|
|
5. Record the adjustment in the active sprint `Execution Log` so the change is traceable.
|
|
|
|
## 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 guidance rendering
|
|
- answer-to-AdvisoryAI handoff
|
|
- priority-route rollout journeys (`findings`, `policy`, `doctor`, `timeline`, `releases`)
|
|
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.
|