diff --git a/docs/implplan/SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md b/docs/implplan/SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md new file mode 100644 index 000000000..314687f08 --- /dev/null +++ b/docs/implplan/SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md @@ -0,0 +1,64 @@ +# Sprint 20260307-017 - Search Zero-Learning Consolidation Strategy + +## Topic & Scope +- Capture the search/advisory redesign as a zero-learning product strategy rather than incremental control polish. +- Record the live suggestion failure that proves current static chips are not corpus-aware. +- Define phased implementation sprints with clear FE/backend/test ownership. +- Working directory: `docs/`. +- Expected evidence: strategy doc, phased sprint files, execution-log evidence for live failure, and explicit optional-telemetry guidance. + +## Dependencies & Concurrency +- Depends on the shipped contextual search and self-serve answer work already documented in `SPRINT_20260307_004` and `SPRINT_20260307_005`. +- Safe parallelism: + - FE and AdvisoryAI implementation can proceed in parallel after this phase freezes the target UX model. + - Live E2E work should wait until phases 1-3 stabilize their contracts. + +## Documentation Prerequisites +- `docs/modules/advisory-ai/knowledge-search.md` +- `docs/modules/advisory-ai/unified-search-architecture.md` +- `docs/modules/ui/search-zero-learning-primary-entry.md` + +## Delivery Tracker + +### DOCS-ZL-001 - Record current UX and reliability failures +Status: DONE +Dependency: none +Owners: Project Manager, Documentation author +Task description: +- Document the current conceptual overload in search: explicit modes, explicit scope control, recovery-panel language, and split search/chat entry points. +- Record live evidence showing that rendered suggestion chips can fail because the active corpus is empty or insufficient. + +Completion criteria: +- [x] The strategy doc records the current UX problems in product terms. +- [x] The strategy doc records the live suggestion failure and why it matters. + +### DOCS-ZL-002 - Freeze the target interaction model and phase plan +Status: DONE +Dependency: DOCS-ZL-001 +Owners: Project Manager +Task description: +- Define the target zero-learning search model and break it into delivery phases that implementation teams can execute without ambiguity. + +Completion criteria: +- [x] The target interaction rules are explicit. +- [x] Phase ownership is split across FE, AdvisoryAI, and Playwright verification. +- [x] Optional telemetry is stated as a non-negotiable requirement. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-07 | Sprint created to reframe search as Stella Ops' primary self-serve entry point. | Project Manager | +| 2026-03-07 | Verified a live failure against the running AdvisoryAI service at `http://127.1.0.44`: knowledge rebuild returned `documentCount=0`, `chunkCount=0`, and `doctorProjectionCount=0`; unified rebuild returned only `chunkCount=14`; querying `database connectivity` returned zero cards while the UI still advertised that suggestion. | Test Automation | +| 2026-03-07 | Published the zero-learning search strategy and phased sprint set for FE consolidation, backend ranking/viability work, and live reliability enforcement. | Documentation author | + +## Decisions & Risks +- Decision: search is the primary entry; AdvisoryAI becomes a secondary deep-dive action launched from search. +- Decision: explicit search modes and explicit scope controls are product debt and should be removed from the main interaction. +- Decision: telemetry remains optional and additive. +- Risk: current static suggestion chips can mislead users when the active corpus is empty. +- Mitigation: introduce suggestion viability gating and live corpus preflight in later phases. + +## Next Checkpoints +- 2026-03-08: Start phase 1 FE consolidation. +- 2026-03-09: Start phase 2 backend implicit-scope and suggestion-viability work. +- 2026-03-10: Run the live reliability matrix over the new contract. diff --git a/docs/implplan/SPRINT_20260307_018_FE_search_primary_entry_consolidation.md b/docs/implplan/SPRINT_20260307_018_FE_search_primary_entry_consolidation.md new file mode 100644 index 000000000..b7b0c764a --- /dev/null +++ b/docs/implplan/SPRINT_20260307_018_FE_search_primary_entry_consolidation.md @@ -0,0 +1,86 @@ +# Sprint 20260307-018 - FE Search Primary Entry Consolidation + +## Topic & Scope +- Make search the single primary top-bar entry point and move AdvisoryAI to a secondary icon action beside it. +- Remove explicit search learning controls from the UI: modes, scope toggle, and recovery panel. +- Simplify the empty, correction, result, and history states so users do not need to learn how Stella search works before it helps them. +- Working directory: `src/Web/StellaOps.Web`. +- Expected evidence: Angular unit tests, focused Playwright coverage, updated UI documentation, and a scoped commit. + +## Dependencies & Concurrency +- Depends on `SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md`. +- Safe parallelism: + - AdvisoryAI ranking/viability work in phase 2 can start in parallel once the FE contract assumptions are explicit. + +## Documentation Prerequisites +- `docs/modules/ui/search-zero-learning-primary-entry.md` +- `docs/modules/advisory-ai/knowledge-search.md` + +## Delivery Tracker + +### FE-ZL-001 - Search-first top-bar entry with secondary chat launcher +Status: TODO +Dependency: none +Owners: Developer (FE) +Task description: +- Keep one primary search input and add a compact AdvisoryAI launcher beside it. +- Opening chat must inherit page context and current query when present. + +Completion criteria: +- [ ] Search remains the primary focus target in the header. +- [ ] AdvisoryAI launches from a secondary icon/button beside search. +- [ ] Existing chat handoff still works from result cards and answer panels. + +### FE-ZL-002 - Remove explicit mode/scope/recovery controls +Status: TODO +Dependency: FE-ZL-001 +Owners: Developer (FE) +Task description: +- Remove the `Find / Explain / Act` segmented control, explicit scope chip, and recovery card panel from the main search UI. +- Move `Did you mean` immediately under the input. + +Completion criteria: +- [ ] No explicit mode control remains in the search panel. +- [ ] No explicit scope toggle remains in the search panel. +- [ ] No recovery panel remains in empty-result states. +- [ ] `Did you mean` renders directly under the input when present. + +### FE-ZL-003 - History cleanup and low-emphasis clear action +Status: TODO +Dependency: FE-ZL-002 +Owners: Developer (FE) +Task description: +- Exclude zero-result history entries from the visible recent-search list. +- Replace the current clear-history button with a discrete icon action. + +Completion criteria: +- [ ] Recent history excludes searches with zero results. +- [ ] Clear-history affordance is icon-based and visually low emphasis. +- [ ] Search history tests cover the new behavior. + +### FE-ZL-004 - Focused FE verification +Status: TODO +Dependency: FE-ZL-003 +Owners: Test Automation +Task description: +- Add or update Angular and Playwright tests for the consolidated UI model. + +Completion criteria: +- [ ] Unit tests cover removed controls and new placement rules. +- [ ] Playwright covers the new top-bar, history, and `Did you mean` behavior. +- [ ] Tests do not rely on deprecated `mode` or `scope` UI controls. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-07 | Sprint created from the zero-learning search strategy. | Project Manager | + +## Decisions & Risks +- Decision: the user should not be asked to choose a search mode before entering a query. +- Decision: page scope becomes implicit UX, not an explicit control. +- Risk: removing explicit controls may expose gaps in backend ranking that modes were previously masking. +- Mitigation: phase 2 adds implicit-scope weighting and answer blending on the backend. + +## Next Checkpoints +- 2026-03-08: Implement FE-ZL-001 through FE-ZL-003. +- 2026-03-08: Run focused FE verification and commit the slice. diff --git a/docs/implplan/SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md b/docs/implplan/SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md new file mode 100644 index 000000000..1592c8527 --- /dev/null +++ b/docs/implplan/SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md @@ -0,0 +1,97 @@ +# Sprint 20260307-019 - AdvisoryAI Implicit Scope Weighting and Suggestion Viability + +## Topic & Scope +- Replace explicit user-controlled search modes with backend intent inference and answer blending. +- Weight current page scope automatically, then surface overflow results from outside the page scope only when they are more sensible than staying narrow. +- Ensure every surfaced suggestion is executable against the active corpus. +- Working directory: `src/AdvisoryAI`. +- Expected evidence: targeted AdvisoryAI tests, live rebuilt-corpus verification, updated API/docs, and a scoped commit. + +## Dependencies & Concurrency +- Depends on `SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md`. +- FE phase 1 can proceed in parallel because this phase preserves additive contracts until FE phase 3 consumes them. + +## Documentation Prerequisites +- `docs/modules/ui/search-zero-learning-primary-entry.md` +- `docs/modules/advisory-ai/knowledge-search.md` +- `docs/modules/advisory-ai/unified-search-architecture.md` + +## Delivery Tracker + +### AI-ZL-001 - Implicit current-scope weighting with overflow fallback +Status: TODO +Dependency: none +Owners: Developer (AdvisoryAI) +Task description: +- Weight current route/domain first, but do not hard-filter the query to that scope. +- Return an explicit overflow set when outside-scope cards are materially stronger than in-scope cards. + +Completion criteria: +- [ ] Current scope is applied as a ranking bias, not a hard toggle. +- [ ] Query responses can distinguish primary in-scope cards from overflow cards. +- [ ] Ranking remains deterministic. + +### AI-ZL-002 - Intent inference and blended answer summaries +Status: TODO +Dependency: AI-ZL-001 +Owners: Developer (AdvisoryAI) +Task description: +- Infer answer shape from the query and evidence instead of relying on client-selected `find`, `explain`, or `act` modes. +- When top results are near-tied, emit a concise blended summary with bounded citations. + +Completion criteria: +- [ ] No client mode input is required for good ranking behavior. +- [ ] Responses can emit a blended summary across close top results. +- [ ] Single-dominant-result behavior remains grounded and explicit. + +### AI-ZL-003 - Suggestion viability and corpus coverage signaling +Status: TODO +Dependency: AI-ZL-001 +Owners: Developer (AdvisoryAI) +Task description: +- Only return suggestions that are executable against the active corpus or domain coverage. +- Add bounded coverage diagnostics so FE can suppress misleading chips when the relevant corpus is empty. + +Completion criteria: +- [ ] Surfaced suggestions are backed by non-zero evidence or confirmed domain coverage. +- [ ] Responses expose enough coverage state for FE to suppress dead suggestions. +- [ ] Live verification covers the previously failing suggestion path. + +### AI-ZL-004 - Optional telemetry preservation +Status: TODO +Dependency: AI-ZL-001 +Owners: Developer (AdvisoryAI) +Task description: +- Preserve telemetry as optional and additive while the ranking and suggestion contracts evolve. + +Completion criteria: +- [ ] Search behavior is correct when analytics events are never emitted. +- [ ] New contracts do not require telemetry to function. + +### AI-ZL-005 - Targeted backend and live verification +Status: TODO +Dependency: AI-ZL-003 +Owners: Test Automation +Task description: +- Add focused tests for implicit scope weighting, overflow results, blended answers, and executable suggestions. +- Re-run the live rebuilt-corpus lane and confirm the prior suggestion failure is either fixed or suppressed correctly. + +Completion criteria: +- [ ] Targeted `.csproj`-level evidence exists for the new ranking contract. +- [ ] Live verification covers at least one formerly failing suggestion path. +- [ ] Execution logs record the exact commands and outcomes. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-07 | Sprint created from the zero-learning search strategy and the reproduced live suggestion failure. | Project Manager | + +## Decisions & Risks +- Decision: implicit scope weighting replaces explicit scope selection in the primary search UX. +- Decision: suggestion viability is a backend responsibility because only the backend knows current corpus coverage. +- Risk: live corpora may be partially empty in local/dev deployments. +- Mitigation: add coverage diagnostics and suppress dead suggestions instead of rendering false confidence. + +## Next Checkpoints +- 2026-03-09: Implement AI-ZL-001 through AI-ZL-003. +- 2026-03-09: Re-run live verification on the suggestion path. diff --git a/docs/implplan/SPRINT_20260307_020_FE_search_result_consolidation_and_chat_handoff.md b/docs/implplan/SPRINT_20260307_020_FE_search_result_consolidation_and_chat_handoff.md new file mode 100644 index 000000000..df18c3cbb --- /dev/null +++ b/docs/implplan/SPRINT_20260307_020_FE_search_result_consolidation_and_chat_handoff.md @@ -0,0 +1,80 @@ +# Sprint 20260307-020 - FE Search Result Consolidation and Chat Handoff + +## Topic & Scope +- Consume the backend's implicit-scope and suggestion-viability contract. +- Present search as a zero-learning result flow with primary in-scope answers, optional overflow results, and secondary chat deep-dive actions. +- Working directory: `src/Web/StellaOps.Web`. +- Expected evidence: Angular unit tests, Playwright coverage, updated docs, and a scoped commit. + +## Dependencies & Concurrency +- Depends on `SPRINT_20260307_018_FE_search_primary_entry_consolidation.md`. +- Depends on `SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md` for the additive response contract. + +## Documentation Prerequisites +- `docs/modules/ui/search-zero-learning-primary-entry.md` +- `docs/modules/advisory-ai/unified-search-architecture.md` + +## Delivery Tracker + +### FE-ZL-005 - Render primary and overflow result sections +Status: TODO +Dependency: none +Owners: Developer (FE) +Task description: +- Render primary in-scope cards first, then an overflow section only when the backend returns stronger outside-scope evidence. + +Completion criteria: +- [ ] Primary and overflow result sections are visually distinct. +- [ ] Overflow is hidden when not returned. +- [ ] No manual scope toggle is reintroduced. + +### FE-ZL-006 - Executable suggestion rendering +Status: TODO +Dependency: FE-ZL-005 +Owners: Developer (FE) +Task description: +- Render only backend-confirmed executable suggestions. +- Hide or downgrade suggestions when the backend signals missing corpus coverage. + +Completion criteria: +- [ ] Dead suggestions are not rendered as clickable chips. +- [ ] Coverage-empty states do not advertise invalid queries. +- [ ] Existing page-suggestion behavior is migrated to the new contract. + +### FE-ZL-007 - Consolidated answer and chat deep-dive handoff +Status: TODO +Dependency: FE-ZL-005 +Owners: Developer (FE) +Task description: +- Keep answer summaries concise and keep chat as the detailed deep-dive path from the new launcher and answer surfaces. + +Completion criteria: +- [ ] Search answers stay concise. +- [ ] Chat handoff is available from the top bar and the answer surface. +- [ ] Handoff carries current query, page context, and top evidence. + +### FE-ZL-008 - Focused FE verification +Status: TODO +Dependency: FE-ZL-006 +Owners: Test Automation +Task description: +- Add or update Playwright and unit coverage for overflow results, executable suggestions, and chat handoff. + +Completion criteria: +- [ ] Tests assert overflow rendering only when the backend returns it. +- [ ] Tests assert that every rendered suggestion is executable. +- [ ] Tests cover the new chat launcher path. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-07 | Sprint created from the zero-learning search strategy. | Project Manager | + +## Decisions & Risks +- Decision: chat is a deep-dive path, not a parallel start experience. +- Risk: old FE code may still assume `mode` or explicit scope controls. +- Mitigation: remove those assumptions in phase 1 before consuming the new contract here. + +## Next Checkpoints +- 2026-03-10: Implement FE-ZL-005 through FE-ZL-007. +- 2026-03-10: Run focused FE verification and commit the slice. diff --git a/docs/implplan/SPRINT_20260307_021_FE_playwright_search_live_reliability_matrix.md b/docs/implplan/SPRINT_20260307_021_FE_playwright_search_live_reliability_matrix.md new file mode 100644 index 000000000..b23b55c87 --- /dev/null +++ b/docs/implplan/SPRINT_20260307_021_FE_playwright_search_live_reliability_matrix.md @@ -0,0 +1,70 @@ +# Sprint 20260307-021 - Playwright Search Live Reliability Matrix + +## Topic & Scope +- Prove the consolidated search experience behaviorally with live and mocked Playwright coverage. +- Guarantee that surfaced suggestions execute successfully in the environments where they are shown. +- Add corpus preflight so live tests fail loudly when coverage is missing instead of silently treating dead suggestions as valid UX. +- Working directory: `src/Web/StellaOps.Web`. +- Expected evidence: Playwright specs, live corpus preflight, command output, and a scoped commit. + +## Dependencies & Concurrency +- Depends on `SPRINT_20260307_018_FE_search_primary_entry_consolidation.md`. +- Depends on `SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md`. +- Depends on `SPRINT_20260307_020_FE_search_result_consolidation_and_chat_handoff.md`. + +## Documentation Prerequisites +- `docs/modules/ui/search-zero-learning-primary-entry.md` +- `docs/operations/unified-search-operations.md` +- `src/AdvisoryAI/__Tests/INFRASTRUCTURE.md` + +## Delivery Tracker + +### QA-ZL-001 - Live corpus preflight +Status: TODO +Dependency: none +Owners: Test Automation +Task description: +- Before running live suggestion flows, assert that the relevant corpus has data for the domains under test. +- Fail fast when the corpus is empty instead of allowing misleading suggestion passes/failures. + +Completion criteria: +- [ ] Live tests verify corpus coverage before exercising knowledge suggestions. +- [ ] Failure output explains whether the issue is corpus emptiness or UX execution. + +### QA-ZL-002 - Suggestion execution guarantee +Status: TODO +Dependency: QA-ZL-001 +Owners: Test Automation +Task description: +- Assert that every rendered suggestion chip returns visible results or is suppressed. + +Completion criteria: +- [ ] Live and mocked specs cover suggestion execution. +- [ ] Surfaced suggestions have 100% visible-result success in the tested matrix. + +### QA-ZL-003 - Zero-learning interaction matrix +Status: TODO +Dependency: QA-ZL-002 +Owners: Test Automation +Task description: +- Cover doctor, findings, policy, timeline, and release routes. +- Assert no explicit mode/scope/recovery controls remain in the main search UX. + +Completion criteria: +- [ ] Route matrix covers the main pages that own contextual search. +- [ ] Tests assert the absence of deprecated controls. +- [ ] Tests assert `Did you mean` placement, history behavior, and chat launcher behavior. + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-07 | Sprint created from the reproduced live suggestion failure and the zero-learning search strategy. | Project Manager | + +## Decisions & Risks +- Decision: live Playwright must distinguish ingestion emptiness from UX failure. +- Risk: a green mocked suite can hide a broken live corpus. +- Mitigation: add explicit live preflight and chip-success assertions. + +## Next Checkpoints +- 2026-03-10: Add live preflight and suggestion execution assertions. +- 2026-03-10: Run the full live reliability matrix. diff --git a/docs/modules/ui/search-zero-learning-primary-entry.md b/docs/modules/ui/search-zero-learning-primary-entry.md new file mode 100644 index 000000000..ce84cc53c --- /dev/null +++ b/docs/modules/ui/search-zero-learning-primary-entry.md @@ -0,0 +1,67 @@ +# Search Zero-Learning Primary Entry + +## Why this exists +- Search must be the default entry into Stella Ops for users who do not know Stella terminology, domain boundaries, or internal product structure. +- The current model asks the user to understand too many concepts before they can succeed: `Find/Explain/Act`, explicit scope switching, recovery actions, and a separate AdvisoryAI destination. +- Live verification also shows a real reliability gap: suggestion chips can render even when the active corpus cannot answer them. On 2026-03-07, the running AdvisoryAI service at `http://127.1.0.44` rebuilt with `documentCount=0`, `chunkCount=0`, and `doctorProjectionCount=0`, while unified overlays rebuilt with only `chunkCount=14`. Querying `database connectivity` then returned zero cards. The current UX still offered that suggestion. + +## Product rules +1. Search is the primary entry point. +2. AdvisoryAI is a secondary deep-dive opened from search, not a competing starting point. +3. Search should infer relevance and intent; the user should not need to choose a mode. +4. Search should bias to the current page context automatically; the user should not need to toggle scope. +5. Search should never advertise a suggestion that cannot execute against the active corpus. +6. Search history should contain only successful searches. +7. Telemetry remains optional. Search behavior must not depend on analytics emission. + +## Target interaction model +### Entry +- Keep one primary search field in the top bar. +- Add a compact AdvisoryAI launcher icon beside the search input. +- Opening chat from that icon inherits the current page, current query, and top evidence when available. + +### Query understanding +- Infer likely user intent from the query and visible page context. +- Weight current page/domain first. +- If current-scope evidence is weak, show overflow results from outside the page scope below the in-scope section instead of asking the user to broaden scope manually. + +### Result presentation +- Place `Did you mean` directly below the input because it is an input correction, not a result refinement. +- Remove explicit `Find / Explain / Act` controls. +- Remove the explicit scope toggle chip. +- Remove the recovery panel. +- If top results are close in score, compose one short summary across them. +- If one result is clearly dominant, present that answer first and then cards. + +### Suggestions +- Page suggestions become executable search intents, not static chips. +- A suggestion is only shown if: + - its preferred domain has live evidence, or + - the backend confirms non-zero candidate coverage for it. +- If the current corpus is empty for that page/domain, suppress those suggestion chips instead of showing dead leads. + +### History +- Persist and render only searches that returned results. +- Keep history clear as a low-emphasis icon action, not a labeled call-to-action. + +## Runtime rules +### Implicit scope weighting +- Current route/domain is a ranking boost, not a hard filter. +- Visible entity keys and last action increase local relevance. +- Out-of-scope results are still allowed, but only after in-scope candidates are exhausted or materially weaker. + +### Answer blending +- If top-N cards fall within a narrow score band, emit a blended summary with citations from multiple cards. +- If score separation is strong, emit a single-result grounded answer. +- The frontend should not ask the user to choose whether they want `find` or `explain`; the backend should infer the dominant answer shape. + +### Suggestion viability +- Suggestions must be validated against the current corpus before rendering. +- Knowledge/domain emptiness should be detectable so the UI can suppress invalid chips. +- Live Playwright coverage must assert that every surfaced suggestion returns visible results. + +## Phase map +- Phase 1: FE primary-entry consolidation and removal of explicit search controls. +- Phase 2: AdvisoryAI implicit scope weighting, answer blending, and suggestion viability. +- Phase 3: FE consumption of overflow results and executable suggestion contracts. +- Phase 4: Live Playwright reliability matrix with corpus preflight and chip-success guarantees.