Render clarify search prompts as guidance only

docs-archived/implplan/SPRINT_20260308_011_FE_search_clarify_guidance_not_query.md

@@ -0,0 +1,77 @@
+# Sprint 20260308-011 - FE Search Clarify Guidance Not Query
+
+## Topic & Scope
+- Stop rendering clarify prompts as executable search suggestions when they are only asking the operator to narrow the target.
+- Fix the release route wording so `/releases/**` no longer suggests dead natural-language queries like "Which environment or release should I narrow this to?".
+- Cover the behavior with component and browser tests so dead clarify prompts do not regress back into the shipped search experience.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: component tests, Playwright regression, and updated UI contract docs.
+
+## Dependencies & Concurrency
+- Depends on the archived search rollout/correction sprints and the archived live search setup lane.
+- Safe parallelism: do not edit unrelated Router, release cutover, or audit-bundle files while executing this search-only fix.
+- Cross-module allowance: documentation updates may touch `docs/modules/ui/**` when clarifying the search self-serve contract.
+
+## Documentation Prerequisites
+- `src/Web/StellaOps.Web/AGENTS.md`
+- `docs/modules/ui/search-self-serve-contract.md`
+- `docs/modules/ui/search-zero-learning-primary-entry.md`
+
+## Delivery Tracker
+
+### FE-CLARIFY-001 - Treat clarify prompts as guidance, not runnable search chips
+Status: DONE
+Dependency: none
+Owners: Developer (FE), QA
+Task description:
+- Update the global search answer panel so clarify prompts are rendered as guidance hints instead of clickable search chips.
+- Keep grounded follow-up questions executable; only the clarify branch should stop behaving like a query launcher.
+
+Completion criteria:
+- [x] Clarify prompts no longer execute searches when rendered from the answer panel.
+- [x] Grounded follow-up questions remain executable.
+- [x] Search UX still offers actionable next steps through viable starters and related searches.
+
+### FE-CLARIFY-002 - Fix release-route clarify wording and regression coverage
+Status: DONE
+Dependency: FE-CLARIFY-001
+Owners: Developer (FE), Test Automation
+Task description:
+- Replace the release clarify wording with guidance phrasing instead of a literal natural-language question.
+- Add unit and Playwright coverage proving the clarify UI is guidance-only and release users do not see the old dead-query text as an executable suggestion.
+
+Completion criteria:
+- [x] Release clarify copy is guidance-oriented.
+- [x] Unit coverage proves clarify prompts are guidance-only.
+- [x] Playwright regression covers the clarify-answer rendering path.
+
+### FE-CLARIFY-003 - Document and close
+Status: DONE
+Dependency: FE-CLARIFY-002
+Owners: Documentation, Project Manager
+Task description:
+- Update the UI search contract docs to state that clarify prompts are explanatory narrowing guidance, not executable searches.
+- Archive the sprint after implementation and evidence are recorded.
+
+Completion criteria:
+- [x] UI docs reflect the clarify-guidance behavior.
+- [x] Execution log captures code/test evidence.
+- [x] Sprint is archived only after all tasks are DONE.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-08 | Sprint created to stop dead clarify prompts from being surfaced like runnable searches. | Developer |
+| 2026-03-08 | Updated global search clarify rendering to guidance-only rows, changed route clarifier copy to narrowing guidance, and kept grounded follow-up questions executable. | Developer |
+| 2026-03-08 | Verified focused FE coverage: `ambient-context.service.spec.ts` + `global-search.component.spec.ts` passed `37/37`; Playwright clarify regression pack passed `18/18`. | QA |
+
+## Decisions & Risks
+- Decision: fix this at the search contract level rather than patching only `/releases/versions`.
+- Risk: clarify prompts currently share the same rendering path as grounded follow-up questions.
+- Mitigation: split the clarify-answer rendering path while keeping grounded follow-ups and related searches untouched.
+- Decision: clarify prompts are now guidance copy everywhere they are generated, so the UI never presents a dead natural-language query as an executable chip.
+- Docs: `docs/modules/ui/search-self-serve-contract.md`, `docs/modules/ui/search-zero-learning-primary-entry.md`.
+
+## Next Checkpoints
+- 2026-03-08: clarify answer panel updated and covered by tests.
+- 2026-03-08: sprint archived after green regression coverage.