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.
|
||||
Reference in New Issue
Block a user