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

Plan zero-learning search consolidation phases

Browse Source
This commit is contained in:
master
2026-03-07 17:22:20 +02:00
parent f1ab38aa27
commit b429341f10
6 changed files with 464 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/implplan/SPRINT_20260307_017_DOCS_search_zero_learning_consolidation_strategy.md Normal file
View File

@@ -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.

86
docs/implplan/SPRINT_20260307_018_FE_search_primary_entry_consolidation.md Normal file
View File

@@ -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.

97
docs/implplan/SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md Normal file
View File

@@ -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.

80
docs/implplan/SPRINT_20260307_020_FE_search_result_consolidation_and_chat_handoff.md Normal file
View File

@@ -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.

70
docs/implplan/SPRINT_20260307_021_FE_playwright_search_live_reliability_matrix.md Normal file
View File

@@ -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.

67
docs/modules/ui/search-zero-learning-primary-entry.md Normal file
View File

@@ -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.