Improve search and advisory UX flows
This commit is contained in:
master
@@ -0,0 +1,136 @@
|
||||
# Sprint 20260306-002 - Search and Advisory Quality UX
|
||||
|
||||
## Topic & Scope
|
||||
- Upgrade global search and AdvisoryAI UX from "smart suggestions" to "explainable operator guidance" with visible context, rationale, and next-step framing.
|
||||
- Make contextual search state legible: current page, active domain, and latest meaningful action should be visible in the search surface.
|
||||
- Improve suggestion quality UX with richer chips that explain why they are being suggested and what type of action they represent.
|
||||
- Working directory: `src/Web/StellaOps.Web`.
|
||||
- Expected evidence: Angular unit tests, Playwright behavioral tests, updated UI docs, and sprint execution log entries.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md` for ambient context capture and chip registry groundwork.
|
||||
- Upstream implementation points:
|
||||
- `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/advisory-ai/chat/chat-message.component.ts`
|
||||
- Safe parallelism:
|
||||
- UI presentation work can run in parallel with docs updates once chip-view contract is frozen.
|
||||
- Search mode / zero-result rescue tasks should start after context-rail patterns are 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-UX-001 - Search context rail and explainable chips
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Add a visible context rail to the global search panel that shows:
|
||||
- current page context
|
||||
- active domain focus
|
||||
- most recent meaningful action on the current page
|
||||
- Upgrade chip rendering so suggestion chips can expose rationale text and suggestion intent/category instead of showing only raw query text.
|
||||
- Keep the layout compact enough for header search use while remaining legible on mobile.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Empty-state search renders a context rail with page/domain/last-action information when available.
|
||||
- [x] Suggestion chips can render rationale text from the shared chip contract.
|
||||
- [x] Unit and Playwright coverage validate the new UI behavior.
|
||||
|
||||
### FE-UX-002 - Search modes across search and AdvisoryAI
|
||||
Status: DONE
|
||||
Dependency: FE-UX-001
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Introduce explicit operator modes for the search/advisory experience:
|
||||
- `Find`
|
||||
- `Explain`
|
||||
- `Act`
|
||||
- Use the selected mode to influence chip ordering, Ask-AI prompts, and zero-result rescue actions.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Mode switch is visible and keyboard accessible.
|
||||
- [x] Search and Ask-AI handoff respect the selected mode.
|
||||
- [x] Docs describe mode behavior and fallback semantics.
|
||||
|
||||
### FE-UX-003 - Zero-result rescue and reformulation UX
|
||||
Status: DONE
|
||||
Dependency: FE-UX-001
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Improve no-result and sparse-result states with guided recovery actions:
|
||||
- broaden scope
|
||||
- search related domains
|
||||
- ask AdvisoryAI to reformulate
|
||||
- retry with visible entities / current page focus
|
||||
|
||||
Completion criteria:
|
||||
- [x] Zero-result states provide at least three recovery actions.
|
||||
- [x] Recovery actions record contextual intent for follow-up search quality analysis.
|
||||
- [x] Playwright tests cover rescue behavior end-to-end.
|
||||
|
||||
### FE-UX-004 - AdvisoryAI evidence-first next-step cards
|
||||
Status: DONE
|
||||
Dependency: FE-UX-002
|
||||
Owners: Developer (FE), Developer (AdvisoryAI), UX
|
||||
Task description:
|
||||
- Upgrade AdvisoryAI responses to render structured next-step cards for common operator flows:
|
||||
- search deeper
|
||||
- inspect evidence chain
|
||||
- compare policy impact
|
||||
- open timeline / graph / VEX
|
||||
- Keep all actions explicit and provenance-linked.
|
||||
|
||||
Completion criteria:
|
||||
- [x] AdvisoryAI can render at least two structured next-step card types.
|
||||
- [x] Cards preserve evidence-first behavior and do not hide provenance.
|
||||
- [x] Search return flows remain deterministic.
|
||||
|
||||
### FE-UX-005 - Docs sync and rollout notes
|
||||
Status: DONE
|
||||
Dependency: FE-UX-001
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Update UI and AdvisoryAI docs with the new UX contract and rollout guidance.
|
||||
- Record rationale for the chosen quality UX direction and phased delivery order.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Architecture docs reflect context rail + explainable chip behavior.
|
||||
- [x] Sprint Decisions & Risks capture rollout tradeoffs.
|
||||
- [x] Execution log links implementation and verification evidence.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-06 | Sprint created for quality UX improvements on top of contextual search/advisory groundwork. | Project Manager |
|
||||
| 2026-03-06 | FE-UX-001 started: implementing context rail and explainable suggestion chips in global search. | Developer (FE) |
|
||||
| 2026-03-06 | FE-UX-001 completed: added search context rail, explainable suggestion cards, shared registry presentation/reason contract, targeted Angular tests (19/19), and Playwright contextual-suggestions verification (3/3). | Developer (FE) |
|
||||
| 2026-03-06 | FE-UX-002 completed: added shared `Find`/`Explain`/`Act` mode state, keyboard-accessible mode switchers in search and AdvisoryAI, and mode-aware search-to-chat handoff prompts. | Developer (FE) |
|
||||
| 2026-03-06 | FE-UX-003 completed: added zero-result rescue actions for scope broadening, related pivots, page-context retry, and AdvisoryAI reformulation; fixed search-panel focus containment so internal controls do not collapse the surface. | Developer (FE) |
|
||||
| 2026-03-06 | FE-UX-004 completed: AdvisoryAI assistant messages now render evidence-first next-step cards (search, evidence, policy, context) and return structured search intent back into global search deterministically. | Developer (FE) |
|
||||
| 2026-03-06 | FE-UX-005 completed: updated UI and AdvisoryAI docs, added targeted Angular coverage (39/39), and passed Playwright behavioral suites for contextual suggestions plus quality UX flows (7/7). | Developer (FE) |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: the first quality UX slice will prioritize explainability over more hidden ranking logic.
|
||||
- Decision: chip rationale should come from the shared registry/service contract, not component-local hardcoding.
|
||||
- Decision: executable suggestion text and visible rationale must stay separate so clicking a chip always submits only the intended query string.
|
||||
- Decision: search/advisory mode is a shared operator state (`Find`, `Explain`, `Act`) and not a local cosmetic toggle; prompts, chip ranking, and rescue actions all consume the same mode service.
|
||||
- Decision: focus transitions inside the global-search surface must not collapse the panel; mode switches, scope toggles, and rescue buttons are part of the same command surface.
|
||||
- Decision: AdvisoryAI next-step cards remain evidence-first by always exposing a direct evidence/open-context path in addition to search pivots.
|
||||
- Risk: richer chip content may overcrowd the header search dropdown.
|
||||
- Mitigation: use compact rail layout, limit visible chips, and keep rationale to a single short line.
|
||||
- Risk: page/domain labels can drift from actual route behavior.
|
||||
- Mitigation: derive labels from the same shared registry used for suggestion selection and context-rail presentation.
|
||||
- Risk: explicit mode state can drift between search and chat if separate stores are introduced.
|
||||
- Mitigation: keep a single root `SearchExperienceModeService` and verify handoff behavior in unit and Playwright coverage.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-03-07: FE-UX-001 through FE-UX-005 shipped and verified.
|
||||
- 2026-03-09: Monitor search/advisory telemetry for rescue-action usage and mode adoption.
|
||||
- 2026-03-11: Use field feedback to decide whether to add richer per-page card presets beyond search/policy/evidence/context.
|
||||
Reference in New Issue
Block a user