stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Improve search and advisory UX flows

Browse Source
This commit is contained in:
master
2026-03-06 19:13:26 +02:00
parent 06e10883ab
commit 9b86ad825a
20 changed files with 2530 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/modules/ui/TASKS.md
View File

@@ -3,6 +3,7 @@
## Active Sprint Links
- `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`
## Delivery Tasks
- [DONE] 041-T1 Root IA/nav rewrite (Mission Control + Ops + Setup)
@@ -21,5 +22,13 @@
- [DONE] WEB-CTX-003 FE -> AdvisoryAI ambient payload activation
- [DOING] WEB-CTX-005 Context-aware suggestion UX updates
- [DOING] WEB-CTX-007 Docs sync and rollout plan
- [DONE] WEB-CTX-005A Playwright exhaustive query matrix (>1000 query types)
- [DONE] FE-UX-001 Search context rail and explainable chips
- [DONE] FE-UX-002 Search/AdvisoryAI shared mode switch (`Find` / `Explain` / `Act`)
- [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] 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)
- [DOING] FE-QA-LOOP-001 Web-only Playwright full-iteration loop at stella-ops.local (fresh route/action evidence, triage, fix, retest)

6
docs/modules/ui/architecture.md
View File

@@ -194,8 +194,14 @@ Each feature folder builds as a **standalone route** (lazy loaded). All HTTP sha
* **Assistant -> search return**: assistant responses expose `Search for more` and `Search related` actions; these populate global search query/domain context and focus the search surface.
* **Guided discovery empty state**: when global search is focused with an empty query, the panel renders an 8-domain guide (findings, VEX, policy, docs, API, health, operations, timeline), contextual suggestion chips, and quick actions (`Getting Started`, `Run Health Check`, `View Recent Scans`).
* **Automatic page-open suggestions**: `AmbientContextService` tracks router navigation and updates global-search suggestion chips/placeholders automatically for every opened page without requiring manual refresh.
* **Context rail**: empty-state search also renders a compact rail showing the current page title/description, active domain scope, and last meaningful action on the same page scope when available.
* **Last-action follow-up suggestions**: the same service keeps a per-route scoped last action (search result open/action, Ask AI handoff, chat return actions) with deterministic TTL bounds; empty-state chips prepend a contextual `follow up: ...` suggestion when available.
* **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.
* **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`.
* **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.

30
docs/modules/ui/search-chip-context-contract.md
View File

@@ -11,14 +11,22 @@
- Context definitions must provide:
- `id`
- `routePrefixes`
- `presentation` (`titleKey/titleFallback`, `descriptionKey/descriptionFallback`) for the search context rail
- optional `domain`
- optional `searchSuggestions[]`
- optional `chatSuggestions[]`
- optional `chatRoutePattern`
- Search suggestion entries should provide:
- `key` / `fallback` for the executable query text
- `reasonKey` / `reasonFallback` for the visible "why this suggestion" line
- optional `kind` (`page`, `recent`, `strategy`) when page teams need non-default styling/priority
- optional `preferredModes` (`find`, `explain`, `act`) when a chip should rank higher for a specific operator intent
- Suggestion arrays must stay deterministic and bounded:
- at most 3 base chips per page context
- short, action-oriented text
- no tenant/user secrets in fallback text
- keep the query label distinct from rationale text so suggestion clicks always submit the intended query only
- fallback copy should still make sense after mode-aware reordering; do not encode mode-specific rationale into the raw query text
## Source of truth
- Contract and registry:
@@ -27,17 +35,35 @@
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
## Runtime behavior
- The empty-state search panel renders a context rail with:
- page title/description from `presentation`
- active domain token when available
- last-action token when recent scoped action history exists
- Base chips come from the page context array.
- A deterministic rotation (session + route scope + 5-minute bucket) varies chip order.
- Last few actions for the current page scope are tracked (bounded history, TTL 15 minutes).
- Up to 2 `follow up: ...` chips are generated from recent actions and prioritized above base chips.
- One strategic chip is generated from dominant/recent action intent.
- Generated chips must also expose rationale metadata:
- `recent` chips explain they came from last-page actions
- `strategy` chips explain they came from recent intent on the same page scope
- Mode-aware ranking:
- the shared `SearchExperienceModeService` owns the active operator mode
- chips marked with `preferredModes` are ranked ahead of otherwise-equal chips for that mode
- page teams should use this sparingly to express clear intent differences, not to create large per-mode chip forks
- Search-surface control rule:
- buttons inside the search surface (mode switch, scope toggle, rescue cards, filters) are part of the same command workspace
- focus transitions into those controls must not collapse the search panel
- teams adding new controls inside the panel must preserve this containment rule in tests
## Page ownership workflow
1. Add/adjust a context in `SEARCH_CONTEXT_DEFINITIONS`.
2. Ensure page component exposes the same `searchContextId` (implements `SearchContextComponent`).
3. Add/adjust unit tests in `ambient-context.service.spec.ts`.
4. Add/adjust Playwright tests for route chips + action-driven chips.
3. Define or update `presentation` copy for the context rail.
4. Add or update `reasonFallback` text and any `preferredModes` metadata for each base chip.
5. Add/adjust unit tests in `ambient-context.service.spec.ts`.
6. Add/adjust Playwright tests for route chips + action-driven chips.
7. If the page adds custom controls inside the search panel, add focus-containment coverage so those controls do not dismiss the panel.
## Non-goals
- No unbounded per-page suggestion memory.