git.stella-ops.org/docs/modules/ui/search-self-serve-contract.md

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.