Add answer-first self-serve search UX
This commit is contained in:
master
@@ -0,0 +1,118 @@
|
||||
# Sprint 20260307-004 - FE Self-Serve Search Answer-First
|
||||
|
||||
## Topic & Scope
|
||||
- Turn global search into an answer-first operator surface instead of a link list by rendering a grounded answer or explicit fallback for every query.
|
||||
- Add a page-owned self-serve contract so each page can define common questions and clarifying prompts without hardcoding logic inside `GlobalSearchComponent`.
|
||||
- Keep phase 1 frontend-only: compose the new experience from route context, recent page actions, unified search cards, and existing synthesis payloads.
|
||||
- Working directory: `src/Web/StellaOps.Web`.
|
||||
- Expected evidence: Angular unit tests, Playwright behavioral coverage, updated UI/AdvisoryAI docs, and sprint execution log entries.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on:
|
||||
- `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md`
|
||||
- `docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md`
|
||||
- This sprint intentionally avoids backend contract changes so FE can ship a self-serve shell while backend orchestration work proceeds separately.
|
||||
- Safe parallelism:
|
||||
- Docs updates can run once the self-serve contract is frozen.
|
||||
- Additional page rollouts can happen in parallel after the core answer panel structure is stable.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/ui/architecture.md`
|
||||
- `docs/modules/ui/search-chip-context-contract.md`
|
||||
- `docs/modules/ui/implementation_plan.md`
|
||||
- `docs/modules/advisory-ai/knowledge-search.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### FE-SELF-001 - Page-owned self-serve contract
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Extend the shared search context registry so page teams can define self-serve questions and clarification prompts alongside existing chip definitions.
|
||||
- Keep the contract deterministic, bounded, and explicit about page ownership so future route teams can add self-serve behavior without touching ranking internals.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Shared FE contract supports page-owned common questions and clarifying questions.
|
||||
- [x] Runtime composition can blend page definitions with recent-action context without unbounded state.
|
||||
- [x] Contract is documented for future page teams.
|
||||
|
||||
### FE-SELF-002 - Answer-first search panel
|
||||
Status: DONE
|
||||
Dependency: FE-SELF-001
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Add a visible answer panel above results for every non-empty search.
|
||||
- The panel must render one of three explicit states:
|
||||
- grounded answer
|
||||
- clarification needed
|
||||
- insufficient evidence
|
||||
- Frame copy by the shared `Find` / `Explain` / `Act` mode so the same evidence reads differently depending on operator intent.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Query responses always render an answer-state panel before result cards or rescue guidance.
|
||||
- [x] Grounded answers expose evidence summary and visible source references.
|
||||
- [x] Clarification and insufficient-evidence states are explicit and non-empty.
|
||||
|
||||
### FE-SELF-003 - Common questions and follow-up questions
|
||||
Status: DONE
|
||||
Dependency: FE-SELF-001
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Surface page-owned common questions in the empty state and mode-aware follow-up questions after results.
|
||||
- Blend route context with last-page actions so questions feel tied to what the operator was just doing.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Empty-state search shows page-specific common questions when available.
|
||||
- [x] Result-state answer panel shows follow-up or clarifying questions derived from page context.
|
||||
- [x] Question clicks deterministically rerun search with the exact selected query text.
|
||||
|
||||
### FE-SELF-004 - Verification and behavior hardening
|
||||
Status: DONE
|
||||
Dependency: FE-SELF-002
|
||||
Owners: Test Automation, QA, Developer (FE)
|
||||
Task description:
|
||||
- Add targeted unit coverage for answer-state selection, question generation, and fallback behavior.
|
||||
- Add Playwright coverage for grounded-answer, clarification, and no-evidence journeys end to end.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Unit coverage validates answer-state selection and contextual question generation.
|
||||
- [x] Playwright covers grounded-answer, clarify, and fallback flows.
|
||||
- [x] Tests remain deterministic with route mocks and no live network dependencies.
|
||||
|
||||
### FE-SELF-005 - Docs sync and rollout guidance
|
||||
Status: DONE
|
||||
Dependency: FE-SELF-001
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Update UI and AdvisoryAI docs so the new self-serve search contract is explicit.
|
||||
- Record what phase 1 does in FE and what remains for later backend grounding work.
|
||||
|
||||
Completion criteria:
|
||||
- [x] UI docs describe the self-serve page contract and answer-first behavior.
|
||||
- [x] AdvisoryAI docs describe FE-first answer composition and future backend ownership.
|
||||
- [x] Sprint Decisions & Risks capture the phase split and its rationale.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-07 | Sprint created for answer-first self-serve search UX. | Project Manager |
|
||||
| 2026-03-07 | FE-SELF-001 started: defining page-owned self-serve questions and answer-first UI slice. | Developer (FE) |
|
||||
| 2026-03-07 | FE-SELF-001 through FE-SELF-003 completed: added page-owned self-serve questions/clarifiers in `search-context.registry.ts`, recent-action question composition in `ambient-context.service.ts`, and answer-first/common-question UI in `global-search.component.ts`. | Developer (FE) |
|
||||
| 2026-03-07 | FE-SELF-004 completed: Angular targeted tests passed 30/30 (`ambient-context.service.spec.ts`, `global-search.component.spec.ts`); Playwright self-serve + regression suites passed 10/10 across contextual, quality, and self-serve specs. | Test Automation |
|
||||
| 2026-03-07 | FE-SELF-005 completed: added `docs/modules/ui/search-self-serve-contract.md` and synced UI/AdvisoryAI docs to document FE-first answer composition and future backend grounding follow-up. | Documentation author |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: phase 1 is frontend-composed on top of existing unified search payloads so the product can ship a self-serve shell immediately.
|
||||
- Decision: page ownership must live in the shared search context registry, not in ad hoc component conditionals.
|
||||
- Decision: every non-empty search must render a visible answer state even when the answer is only a clarification request or insufficient-evidence message.
|
||||
- Decision: self-serve questions are governed by `docs/modules/ui/search-self-serve-contract.md`, while contextual chips remain governed by `docs/modules/ui/search-chip-context-contract.md`.
|
||||
- Risk: FE-composed answers may overstate confidence if they are not visibly tied back to retrieved evidence.
|
||||
- Mitigation: show explicit evidence counts, source references, and fallback states instead of pretending every query has a confident answer.
|
||||
- Risk: adding more content to the search surface can overload the header dropdown.
|
||||
- Mitigation: keep question counts bounded, collapse to short cards/chips, and bias toward operator actions instead of long prose.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-03-07: FE self-serve contract + answer-first UI slice implemented with tests.
|
||||
- 2026-03-10: Backend sprint `SPRINT_20260307_005_AdvisoryAI_grounded_search_answer_orchestration.md` to freeze `contextAnswer` payload shape.
|
||||
- 2026-03-12: Roll the contract out to additional pages via `SPRINT_20260307_006_FE_self_serve_rollout_and_gap_closure.md`.
|
||||
@@ -0,0 +1,107 @@
|
||||
# Sprint 20260307-005 - AdvisoryAI Grounded Search Answer Orchestration
|
||||
|
||||
## Topic & Scope
|
||||
- Move self-serve search from frontend-composed answers to backend-grounded contextual answers with explicit citations, fallback reasons, and follow-up questions.
|
||||
- Establish a unified answer contract that search and AdvisoryAI can both consume.
|
||||
- Add telemetry for unanswered and reformulated journeys so self-serve gaps become measurable backlog items instead of anecdotal feedback.
|
||||
- Working directory: `src/AdvisoryAI`.
|
||||
- Expected evidence: targeted integration tests against the AdvisoryAI test project, updated API/docs, and execution-log entries with command evidence.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on `docs/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md` for the FE shell and contract expectations.
|
||||
- Safe parallelism:
|
||||
- FE rollout work can continue after the answer payload shape is frozen.
|
||||
- Backend ranking and telemetry work can proceed independently of additional page-contract authoring in Web.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/advisory-ai/knowledge-search.md`
|
||||
- `docs/modules/advisory-ai/unified-search-architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
- `docs/code-of-conduct/TESTING_PRACTICES.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### AI-SELF-001 - Unified contextual answer payload
|
||||
Status: TODO
|
||||
Dependency: none
|
||||
Owners: Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Extend unified search responses with contextual answer fields such as answer status, summary, citations, answer reason, and follow-up questions.
|
||||
- Preserve backward compatibility so older Web clients can ignore the new fields safely.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Unified search response contract includes contextual answer and fallback metadata.
|
||||
- [ ] Existing callers remain compatible when new fields are absent.
|
||||
- [ ] API docs describe the new answer payload.
|
||||
|
||||
### AI-SELF-002 - Grounding and fallback policy
|
||||
Status: TODO
|
||||
Dependency: AI-SELF-001
|
||||
Owners: Developer (AdvisoryAI), Product Manager
|
||||
Task description:
|
||||
- Define deterministic rules for when the service may emit:
|
||||
- grounded answer
|
||||
- clarification needed
|
||||
- insufficient evidence
|
||||
- Make the reasoning explicit in payload fields so UI does not have to guess why a state was chosen.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Grounding thresholds are explicit and deterministic.
|
||||
- [ ] Clarification and insufficient-evidence reasons are returned in the payload.
|
||||
- [ ] Synthesis cannot silently masquerade as a grounded answer without sufficient evidence.
|
||||
|
||||
### AI-SELF-003 - Follow-up question and clarification generation
|
||||
Status: TODO
|
||||
Dependency: AI-SELF-001
|
||||
Owners: Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Generate contextual follow-up questions from query intent, page/domain hints, recent actions, and top evidence.
|
||||
- Prefer actionable operator questions over generic reformulations.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Payload includes bounded follow-up question arrays.
|
||||
- [ ] Generation uses page/domain context and query intent deterministically.
|
||||
- [ ] Ambiguous queries return clarifying prompts instead of a blank answer slot.
|
||||
|
||||
### AI-SELF-004 - Self-serve telemetry and gap surfacing
|
||||
Status: TODO
|
||||
Dependency: AI-SELF-002
|
||||
Owners: Developer (AdvisoryAI), Test Automation
|
||||
Task description:
|
||||
- Track unanswered searches, repeated reformulations, rescue-action usage, and abandonment after fallback states.
|
||||
- Expose enough structured data to drive a gap-closure backlog.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Telemetry captures unanswered and reformulated journeys without persisting raw sensitive prompts unnecessarily.
|
||||
- [ ] Operational docs explain how to review self-serve gaps.
|
||||
- [ ] Tests cover telemetry emission for fallback paths.
|
||||
|
||||
### AI-SELF-005 - Targeted behavioral verification
|
||||
Status: TODO
|
||||
Dependency: AI-SELF-003
|
||||
Owners: Test Automation, QA
|
||||
Task description:
|
||||
- Add focused integration tests to the AdvisoryAI test project that exercise grounded, clarify, and insufficient-evidence answer states through the real endpoint contract.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Tests target the specific AdvisoryAI `.csproj`, not a solution filter.
|
||||
- [ ] Assertions verify actual answer-state payload content, not only success status codes.
|
||||
- [ ] Execution log records exact commands and outcomes.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-07 | Sprint created to formalize backend-grounded contextual answers after the FE answer-first shell. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: the backend contract must return explicit answer states instead of leaving the UI to infer confidence from cards alone.
|
||||
- Decision: the product requirement is 100% response framing, not 100% hallucinated AI answers.
|
||||
- Risk: answer payload inflation could make the endpoint harder to evolve if fields are not clearly optional.
|
||||
- Mitigation: use additive optional fields with strict docs and integration coverage.
|
||||
- Risk: telemetry may leak raw user intent if not hashed or summarized carefully.
|
||||
- Mitigation: follow existing hashed-query analytics patterns and avoid raw prompt persistence where not required for history UX.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-03-10: Freeze answer payload shape and fallback taxonomy.
|
||||
- 2026-03-12: Complete endpoint integration tests for answer states.
|
||||
- 2026-03-13: Hand off payload contract to FE rollout sprint.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Sprint 20260307-006 - FE Self-Serve Rollout and Gap Closure
|
||||
|
||||
## Topic & Scope
|
||||
- Roll the self-serve search contract across priority pages so the experience is consistent wherever operators land.
|
||||
- Close the gap between search, AdvisoryAI, and page workflows by wiring guided actions and telemetry-informed improvements.
|
||||
- Convert unanswered journeys into visible UX backlog items and stronger end-to-end coverage.
|
||||
- Working directory: `src/Web/StellaOps.Web`.
|
||||
- Expected evidence: page-contract rollouts, Playwright operator-journey suites, updated docs/task boards, and execution-log entries.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on:
|
||||
- `docs/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md`
|
||||
- `docs/implplan/SPRINT_20260307_005_AdvisoryAI_grounded_search_answer_orchestration.md`
|
||||
- Safe parallelism:
|
||||
- Page-by-page contract authoring can run in parallel once the shared answer panel contract is frozen.
|
||||
- Telemetry review can happen in parallel with guided-action polish.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/ui/architecture.md`
|
||||
- `docs/modules/ui/search-chip-context-contract.md`
|
||||
- `docs/modules/advisory-ai/knowledge-search.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### FE-ROLL-001 - Priority page contract rollout
|
||||
Status: TODO
|
||||
Dependency: none
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Apply the self-serve question contract to priority routes:
|
||||
- findings / triage
|
||||
- policy
|
||||
- doctor / system health
|
||||
- timeline / audit
|
||||
- releases / mission control
|
||||
- Ensure every priority page exposes context rail copy, common questions, and clarifying prompts.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Each priority page has explicit self-serve question definitions.
|
||||
- [ ] Empty-state and answer-state UX remain coherent across the priority routes.
|
||||
- [ ] Page ownership is documented.
|
||||
|
||||
### FE-ROLL-002 - Guided action handoffs
|
||||
Status: TODO
|
||||
Dependency: FE-ROLL-001
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Tighten handoffs from search answers into chat, navigation, and next-search flows.
|
||||
- Reduce dead ends by always pairing answers with a credible next action.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Grounded answers expose at least one next-search or Ask-AdvisoryAI path.
|
||||
- [ ] Clarification and fallback states expose page-relevant recovery actions.
|
||||
- [ ] Handoffs preserve mode and context metadata.
|
||||
|
||||
### FE-ROLL-003 - Telemetry-driven gap review UX
|
||||
Status: TODO
|
||||
Dependency: FE-ROLL-001
|
||||
Owners: Developer (FE), Project Manager
|
||||
Task description:
|
||||
- Add operator-visible and team-visible hooks for low-coverage journeys, including unanswered or repeatedly reformulated searches.
|
||||
- Use telemetry to tune page questions and rescue patterns instead of relying on anecdotal adjustments.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] FE surfaces can emit telemetry markers for self-serve gap analysis.
|
||||
- [ ] Docs explain how unanswered journeys feed backlog prioritization.
|
||||
- [ ] At least one UX adjustment is traceable to telemetry evidence.
|
||||
|
||||
### FE-ROLL-004 - Full operator-journey Playwright coverage
|
||||
Status: TODO
|
||||
Dependency: FE-ROLL-002
|
||||
Owners: Test Automation, QA
|
||||
Task description:
|
||||
- Add end-to-end Playwright suites that verify realistic self-serve journeys from landing on a page through answer, follow-up, and action handoff.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Playwright covers the priority page journeys end to end.
|
||||
- [ ] Tests verify grounded, clarify, and recovery paths.
|
||||
- [ ] Suites remain deterministic with route mocks and local fixtures only.
|
||||
|
||||
### FE-ROLL-005 - Docs and rollout readiness
|
||||
Status: TODO
|
||||
Dependency: FE-ROLL-001
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Update UI architecture and operational guidance so teams know how to adopt and test the self-serve contract.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Docs capture rollout order and page-ownership rules.
|
||||
- [ ] Sprint links and task boards reflect the rollout state.
|
||||
- [ ] Risks and mitigations are documented.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-07 | Sprint created to roll out the self-serve search contract after the answer-first shell and backend answer contract are defined. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: rollout should prioritize high-frequency operator pages before broad route coverage.
|
||||
- Decision: page teams own their self-serve question sets; platform code owns composition and safety rails.
|
||||
- Risk: inconsistent page adoption would make self-serve feel random across the product.
|
||||
- Mitigation: maintain a priority rollout list and explicit page-ownership rules.
|
||||
- Risk: adding guided actions without verification can create shallow or broken handoffs.
|
||||
- Mitigation: require Playwright coverage for each high-value journey.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-03-12: Priority page rollout started after answer contract freeze.
|
||||
- 2026-03-14: Guided handoff journeys verified in Playwright.
|
||||
- 2026-03-16: Gap telemetry reviewed for next backlog cut.
|
||||
@@ -172,6 +172,8 @@ Global search now consumes AKS and supports:
|
||||
- Doctor: `Run` (navigate to doctor and copy run command).
|
||||
- `More` action for "show more like this" local query expansion.
|
||||
- A shared mode switch (`Find`, `Explain`, `Act`) across search and AdvisoryAI with mode-aware chip ranking and handoff prompts.
|
||||
- An answer-first FE shell: every non-empty search renders a visible answer state (`grounded`, `clarify`, `insufficient`) before raw cards, using existing synthesis/cards plus page context until a backend `contextAnswer` payload is introduced.
|
||||
- Page-owned self-serve questions and clarifiers, defined in `docs/modules/ui/search-self-serve-contract.md`, so search can offer "Common questions" and recovery prompts without per-page conditionals in the component.
|
||||
- Zero-result rescue actions that keep the current query visible while broadening scope, trying a related pivot, retrying with page context, or opening AdvisoryAI reformulation.
|
||||
- AdvisoryAI evidence-first next-step cards that can return search pivots (`chat_next_step_search`, `chat_next_step_policy`) back into global search or open cited evidence/context directly.
|
||||
- Search-quality metrics taxonomy is standardized on `query`, `click`, and `zero_result` event types (no legacy `search` event dependency in quality SQL).
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
- `docs/implplan/SPRINT_20260221_041_FE_prealpha_ia_ops_setup_rewire.md`
|
||||
- `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md`
|
||||
- `docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md`
|
||||
- `docs/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md`
|
||||
- `docs/implplan/SPRINT_20260307_006_FE_self_serve_rollout_and_gap_closure.md`
|
||||
|
||||
## Delivery Tasks
|
||||
- [DONE] 041-T1 Root IA/nav rewrite (Mission Control + Ops + Setup)
|
||||
@@ -28,6 +30,16 @@
|
||||
- [DONE] FE-UX-003 Zero-result rescue and reformulation UX
|
||||
- [DONE] FE-UX-004 AdvisoryAI evidence-first next-step cards
|
||||
- [DONE] FE-UX-005 Docs sync and rollout notes for search/advisory quality UX
|
||||
- [DONE] FE-SELF-001 Page-owned self-serve search contract
|
||||
- [DONE] FE-SELF-002 Answer-first search panel
|
||||
- [DONE] FE-SELF-003 Common questions and follow-up questions
|
||||
- [DONE] FE-SELF-004 Self-serve verification and behavior hardening
|
||||
- [DONE] FE-SELF-005 Docs sync and rollout guidance for self-serve search
|
||||
- [TODO] FE-ROLL-001 Priority page self-serve rollout
|
||||
- [TODO] FE-ROLL-002 Guided action handoffs
|
||||
- [TODO] FE-ROLL-003 Telemetry-driven self-serve gap review UX
|
||||
- [TODO] FE-ROLL-004 Full operator-journey Playwright coverage
|
||||
- [TODO] FE-ROLL-005 Docs and rollout readiness
|
||||
- [DONE] WEB-CTX-E2E Playwright coverage for contextual suggestions + ambient last-action payload
|
||||
- [DONE] FE-UX-E2E Playwright coverage for mode switching, rescue flows, and AdvisoryAI next-step cards
|
||||
- [DONE] WEB-CTX-NONOBVIOUS Strategic non-obvious suggestion recipes (cross-domain + action-aware)
|
||||
|
||||
@@ -199,11 +199,13 @@ Each feature folder builds as a **standalone route** (lazy loaded). All HTTP sha
|
||||
* **Strategic non-obvious suggestions**: each page scope injects at least one cross-domain guidance query (for example, findings -> policy/VEX impact, policy -> impacted findings, doctor -> release blockers) and switches to action-aware variants after meaningful user actions.
|
||||
* **Explainable chips**: suggestion queries remain short and executable, while a separate rationale line explains whether a chip comes from page defaults, recent actions, or strategic cross-domain guidance.
|
||||
* **Shared operator modes**: global search and AdvisoryAI share one persisted mode state (`Find`, `Explain`, `Act`) via `SearchExperienceModeService`; the mode changes chip ordering, Ask-AI prompts, empty-state starters, and structured next-step behavior.
|
||||
* **Answer-first search**: every non-empty search renders a visible answer panel before raw cards; the panel must resolve to `grounded`, `clarify`, or `insufficient` and never leave the operator with an unexplained blank result area.
|
||||
* **Page-owned self-serve questions**: priority pages define common questions and clarifying prompts in the shared search context registry; empty-state search uses those as "Common questions" and answer states reuse them as follow-up or clarification buttons.
|
||||
* **Zero-result rescue loop**: no-result states must expose recovery actions for broadening scope, trying a related pivot, retrying with page context, and opening AdvisoryAI reformulation with the active mode and query context preserved.
|
||||
* **Search-surface focus rule**: focus movement into controls inside the global-search surface (mode buttons, scope toggle, rescue buttons, filters) must not collapse the panel; the surface behaves like one command workspace rather than a disposable tooltip.
|
||||
* **AdvisoryAI next-step cards**: assistant responses with citations render structured cards for evidence inspection, context navigation, deeper search, and policy pivots; search-return actions must emit deterministic `chat_next_step_*` metadata back into global search.
|
||||
* **Ambient payload activation**: each global search request sends ambient context (`currentRoute`, `visibleEntityKeys`, `recentSearches`, `sessionId`, optional `lastAction`) so AdvisoryAI can apply contextual ranking/refinement.
|
||||
* **Chip contract governance**: page-owned chip arrays and route mappings are defined by `docs/modules/ui/search-chip-context-contract.md` and implemented in `search-context.registry.ts`.
|
||||
* **Contract governance**: page-owned chip arrays follow `docs/modules/ui/search-chip-context-contract.md`, while answer-first self-serve questions and fallback states follow `docs/modules/ui/search-self-serve-contract.md`; both are implemented in `search-context.registry.ts`.
|
||||
* **Fallback transparency**: when unified search drops to legacy fallback, global search displays an explicit degraded banner and emits enter/exit telemetry markers for operator visibility.
|
||||
|
||||
---
|
||||
|
||||
@@ -8,7 +8,8 @@ Provide a living plan for UI deliverables, dependencies, and evidence.
|
||||
- Update this file when new scoped work is approved.
|
||||
|
||||
## Near-term deliverables
|
||||
- TBD (add when sprint is staffed).
|
||||
- `SPRINT_20260307_004_FE_self_serve_search_answer_first.md` - answer-first search shell, page-owned self-serve questions, and explicit fallback states.
|
||||
- `SPRINT_20260307_006_FE_self_serve_rollout_and_gap_closure.md` - page rollout, guided handoffs, and telemetry-driven gap closure.
|
||||
|
||||
## Dependencies
|
||||
- `docs/modules/ui/architecture.md`
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
- Define one deterministic contract for page-aware search chips.
|
||||
- Let feature teams add page suggestions without editing `AmbientContextService` logic.
|
||||
- Blend route context, last few page actions, and bounded suggestion randomization.
|
||||
- Answer-first self-serve questions and fallback states are governed separately in `docs/modules/ui/search-self-serve-contract.md`.
|
||||
|
||||
## Rule (mandatory for page teams)
|
||||
- Every page that needs custom search chips must declare a context entry in `SEARCH_CONTEXT_DEFINITIONS`.
|
||||
|
||||
65
docs/modules/ui/search-self-serve-contract.md
Normal file
65
docs/modules/ui/search-self-serve-contract.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user