Status: Active
Owner: OSHUN Studio Product Design + Web Engineering + OSHUN BFF
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0021-oshun-studio-search-and-global-discovery.mddocs/releases/v1/specs/studio-search-and-global-discovery-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio search and global discovery governance.
This document is the execution artifact for OST-00067.
Personas#
- Program Operator
- Domain Specialist
- Discovery Analyst
- Security Reviewer
- Accessibility Lead
Journey Principles#
- Discovery queries must produce deterministic and explainable results.
- Domain context must be preserved from search to action.
- Partial failures must degrade gracefully with explicit domain status.
- Search surfaces must be keyboard and screen-reader accessible.
1. Primary Journeys#
J1. Global Query and Cross-Domain Result Discovery#
Goal: Execute one query and discover relevant results across multiple domains.
Entry: Studio -> Search and Discovery -> Global Query
Steps:
- Enter query and optional domain filter.
- Execute query against global search contract.
- Inspect blended and domain-grouped results.
- Review ranking metadata and domain labels.
- Select result and continue into domain workflow.
Success State:
- Relevant, ranked cross-domain results are returned and actionable.
J2. Filtered Discovery for Domain-Specific Work#
Goal: Scope discovery to one domain while preserving global context.
Entry: Studio -> Search and Discovery -> Domain Filter
Steps:
- Select a specific domain filter.
- Execute scoped query.
- Validate result relevance and domain status.
- Open result action route.
- Return to discovery with query/filter state intact.
Success State:
- Scoped results are deterministic and context is preserved after roundtrip.
J3. Query-to-Action Handoff with Context Preservation#
Goal: Move from discovery result to execution surface without losing origin context.
Entry: Result action in search panel
Steps:
- Select result action from list.
- Navigate to mapped route with origin/stack/query context.
- Execute target workflow action.
- Return using preserved back path.
- Confirm restored query state and recent-search continuity.
Success State:
- Action completes and user is returned to correct discovery state.
J4. Partial-Failure Discovery Recovery#
Goal: Continue meaningful discovery when one or more domain sources are degraded.
Entry: Search execution with degraded domain adapters
Steps:
- Execute global query.
- Detect per-domain degraded statuses and errors.
- Show partial-failure signal and domain-level diagnostics.
- Continue exploring healthy-domain results.
- Retry query once degraded domains recover.
Success State:
- Discovery remains usable with clear degraded-domain visibility.
J5. Search Governance Promotion and Rollback#
Goal: Promote search changes safely and recover from regressions.
Entry: Review & Approvals or Observability alert
Steps:
- Review ranking/query/action contract evidence.
- Approve and promote discovery release.
- Monitor quality and latency indicators.
- If regression occurs, rollback to certified release.
- Publish incident summary and remediation tasks.
Success State:
- Discovery release is either stable or safely rolled back with full evidence.
2. Critical Edge Cases#
E1. Empty Query State#
- Trigger: query is blank.
- Required behavior: show deterministic curated defaults (recent/trending).
E2. Invalid Domain Filter#
- Trigger: domain filter is outside supported enum.
- Required behavior: reject request and present clear validation error.
E3. Unauthorized Domain Scope#
- Trigger: user lacks scope for one or more domains.
- Required behavior: mark domains
forbidden, suppress unauthorized results.
E4. Ranking Drift Regression#
- Trigger: ranking order deviates from documented formula.
- Required behavior: fail validation and block release.
E5. Query-to-Route Mapping Missing#
- Trigger: result lacks valid action path.
- Required behavior: disable action, show fallback guidance, emit audit error.
E6. Context Loss on Return Path#
- Trigger: user cannot return to original query/filter context.
- Required behavior: restore from persisted context or safe fallback route.
E7. Partial Domain Outage#
- Trigger: one or more domain adapters fail during query.
- Required behavior: return partial results + explicit domain status and errors.
E8. Search Telemetry Sink Failure#
- Trigger: discovery telemetry or audit emission fails.
- Required behavior: retry, mark degraded observability, reconcile buffered events.
E9. Excessive Search Latency#
- Trigger: search response exceeds defined SLO window.
- Required behavior: alert operators, capture diagnostics, expose user-safe feedback.
E10. Missing Rollback Reference#
- Trigger: discovery release package lacks rollback target.
- Required behavior: block production promotion.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Global Query and Cross-Domain Result Discovery | Search and Discovery | Explore |
| J2 Filtered Discovery for Domain-Specific Work | Search and Discovery | Domain surfaces |
| J3 Query-to-Action Handoff with Context Preservation | Search and Discovery | Navigation, Domain routes |
| J4 Partial-Failure Discovery Recovery | Search and Discovery | Observability |
| J5 Search Governance Promotion and Rollback | Review & Approvals | Observability, Governance |
4. Instrumentation Requirements#
Required events:
search_discovery.journey.startedsearch_discovery.journey.step.completedsearch_discovery.journey.blockedsearch_discovery.journey.recoveredsearch_discovery.journey.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,query,domainFilteractorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00067)#
OST-00067 is complete only when:
- At least five search/discovery journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.