# OSHUN Studio Search and Global Discovery Journeys and Edge Cases

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.md`
- `docs/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

1. Discovery queries must produce deterministic and explainable results.
2. Domain context must be preserved from search to action.
3. Partial failures must degrade gracefully with explicit domain status.
4. 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**:

1. Enter query and optional domain filter.
2. Execute query against global search contract.
3. Inspect blended and domain-grouped results.
4. Review ranking metadata and domain labels.
5. 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**:

1. Select a specific domain filter.
2. Execute scoped query.
3. Validate result relevance and domain status.
4. Open result action route.
5. 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**:

1. Select result action from list.
2. Navigate to mapped route with origin/stack/query context.
3. Execute target workflow action.
4. Return using preserved back path.
5. 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**:

1. Execute global query.
2. Detect per-domain degraded statuses and errors.
3. Show partial-failure signal and domain-level diagnostics.
4. Continue exploring healthy-domain results.
5. 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**:

1. Review ranking/query/action contract evidence.
2. Approve and promote discovery release.
3. Monitor quality and latency indicators.
4. If regression occurs, rollback to certified release.
5. 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.started`
- `search_discovery.journey.step.completed`
- `search_discovery.journey.blocked`
- `search_discovery.journey.recovered`
- `search_discovery.journey.completed`

Required dimensions:

- `programId`, `projectId`, `workspaceId`
- `journeyId`, `stepId`, `query`, `domainFilter`
- `actorRole`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00067)

`OST-00067` is complete only when:

1. At least five search/discovery journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
