# OSHUN Studio IA User Journeys and Edge Cases

Status: Active  
Owner: OSHUN Studio Product + UX Architecture  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0013-oshun-studio-information-architecture.md`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`

## Purpose

Define primary user journeys and edge-case behavior for OSHUN Studio information
architecture across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian
program operations.

This document is the execution artifact for `OST-00003`:

- Design primary user journeys and edge cases.

## Personas and Roles

- Executive Producer (program-level approvals and release gates)
- Creative Director (narrative, style, and quality direction)
- Technical Director (pipeline, build, and runtime quality)
- Domain Specialist (generation, worldbuilding, animation, engine)
- Producer/Coordinator (scheduling, assignments, progress and blockers)
- Reviewer/QA (artifact validation and readiness signoff)

## Journey Design Principles

1. Preserve context (`programId`, `projectId`, `workspaceId`) at all times.
2. Keep critical workflows executable in <= 5 major steps.
3. Surface system state continuously for long-running operations.
4. Allow optimistic progress with explicit rollback and recovery paths.
5. Never dead-end the user on error: always provide next safe actions.

## 1. Primary Journeys

### J1. Program Bootstrap (Project Obsidian)

**Goal**: Create and initialize a franchise-scale production program with
cross-domain visibility.

**Entry**: `Programs -> Create Program`

**Steps**:

1. Create program (`ProgramContext`) with governance template.
2. Create/attach projects and workspaces in Yemaya.
3. Attach world canon root in Hathor.
4. Configure generation defaults and cost controls in Isis.
5. Configure motion standards in Aja.
6. Configure build/export targets in Bellona.
7. Publish execution dashboard and initial release gates.

**Success State**:

- Program dashboard shows all attached projects/domains.
- Baseline release gates are `pending` with assigned approvers.
- Cross-domain context propagation validates in health panel.

### J2. World-to-Asset-to-Build Pipeline

**Goal**: Turn a world/narrative change into build-ready runtime artifacts.

**Entry**: `World & Narrative` or `Programs -> Milestone`

**Steps**:

1. Edit world/narrative in Hathor and pass lore validation.
2. Trigger generation package in Isis using world constraints.
3. Trigger motion package in Aja for associated scene/performance needs.
4. Review outputs in Yemaya asset review queue.
5. Trigger Bellona build/export for selected engine/platform targets.
6. Inspect artifacts, diagnostics, and quality outcomes.
7. Mark milestone evidence as complete.

**Success State**:

- Every artifact has lineage across Hathor/Isis/Aja/Bellona.
- Build artifacts are downloadable and attached to milestone.
- Gate moves from `pending` to `in_review`.

### J3. Expert Iteration Loop (Fast Revisions)

**Goal**: Iterate quickly on assets or narrative branches with low friction.

**Entry**: `Assets`, `Generation`, or `World & Narrative`

**Steps**:

1. Clone previous workflow/version/branch.
2. Apply targeted edits (prompt/constraint/animation/world state).
3. Execute isolated job with scoped resources and priority.
4. Compare outputs side-by-side with quality metrics.
5. Promote chosen output and archive rejected variants.

**Success State**:

- Revision lineage preserved and queryable.
- Promotion action updates downstream references automatically.
- No context switching required between domain surfaces.

### J4. Cross-Team Review and Approval

**Goal**: Complete collaborative review with traceable decision history.

**Entry**: `Review & Approvals`

**Steps**:

1. Open review package for milestone/asset/build.
2. Gather comments, annotations, and required changes.
3. Route to assigned approvers by role.
4. Resolve findings and re-submit package.
5. Capture final decision with evidence links.

**Success State**:

- Approval record includes actor, timestamp, rationale, and evidence.
- Rejections include explicit actionable requirements.
- Audit trail is immutable and searchable.

### J5. Operational Recovery During Partial Outage

**Goal**: Continue production when one domain is degraded.

**Entry**: `Observability` alert or in-flow error state.

**Steps**:

1. Surface degraded dependency and impacted workflows.
2. Offer fallback choices (retry, queue, alternate provider/path).
3. Preserve queued intent and context.
4. Resume operation automatically on dependency recovery.
5. Reconcile final state with audit and timeline updates.

**Success State**:

- User does not lose in-progress work.
- All deferred operations are tracked and replayable.
- Post-recovery status is explicit and verifiable.

## 2. Edge Cases and Required Behavior

### E1. Missing or Invalid Program Context

- **Trigger**: Route opened without valid `programId`/`projectId`.
- **Required Behavior**:
  - Block destructive actions.
  - Show context resolver panel.
  - Allow user to rebind to valid workspace/project.

### E2. Permission Mismatch (Role vs Action)

- **Trigger**: User attempts privileged action without entitlement.
- **Required Behavior**:
  - Present clear permission reason.
  - Offer escalation/request-access flow.
  - Log denied action to audit and analytics.

### E3. Domain Outage (Isis/Aja/Hathor/Bellona)

- **Trigger**: dependency health check fails.
- **Required Behavior**:
  - Keep unaffected surfaces active.
  - Display scoped impact summary.
  - Queue retryable intents with user confirmation.

### E4. Long-Running Job Timeout

- **Trigger**: job exceeds expected SLA window.
- **Required Behavior**:
  - Keep streaming progress or heartbeat status.
  - Offer reprioritize/cancel/split workflow options.
  - Escalate to operational alerts after threshold breach.

### E5. Data Contract Version Drift

- **Trigger**: incoming payload missing required contract fields.
- **Required Behavior**:
  - Mark action as blocked with contract diagnostics.
  - Provide schema diff details for operators.
  - Avoid silent fallback that could corrupt lineage.

### E6. Conflicting Edits (Narrative/Asset Versions)

- **Trigger**: concurrent modifications to same entity branch.
- **Required Behavior**:
  - Show structured diff and conflict classes.
  - Support source/target/custom merge strategy.
  - Preserve both versions and merge decision audit.

### E7. Budget/Cost Guardrail Breach

- **Trigger**: operation exceeds budget policy.
- **Required Behavior**:
  - Pre-flight warning with projected cost.
  - Require approval override for protected tiers.
  - Log decision and override rationale.

### E8. Incomplete Lineage Chain

- **Trigger**: artifact missing provenance edges.
- **Required Behavior**:
  - Mark artifact as non-promotable.
  - Provide lineage repair workflow.
  - Require completion before release gate approval.

### E9. Build Export Failure After Upstream Success

- **Trigger**: Bellona build/export fails after successful generation/motion.
- **Required Behavior**:
  - Keep upstream outputs intact.
  - Provide deterministic rebuild options with cached inputs.
  - Link failure diagnostics to build and milestone timelines.

### E10. Approval Deadlock

- **Trigger**: required approvers unavailable or conflicting.
- **Required Behavior**:
  - Escalation chain with SLA timers.
  - Temporary delegated authority policies.
  - Explicit deadlock state and unblock actions.

## 3. Journey-to-Surface Mapping

| Journey                    | Primary Surface     | Supporting Surfaces                         |
| -------------------------- | ------------------- | ------------------------------------------- |
| J1 Program Bootstrap       | Programs            | Projects, Governance, Observability         |
| J2 World-to-Asset-to-Build | World & Narrative   | Generation, Motion, Assets, Build & Runtime |
| J3 Expert Iteration Loop   | Generation / Assets | World & Narrative, Motion, Build & Runtime  |
| J4 Review and Approval     | Review & Approvals  | Assets, Build & Runtime, Governance         |
| J5 Outage Recovery         | Observability       | Any impacted domain surface                 |

## 4. Instrumentation Requirements per Journey

For each journey and edge case, emit at minimum:

- `journey.started`
- `journey.step.completed`
- `journey.blocked`
- `journey.recovered`
- `journey.completed`

Required dimensions:

- `programId`, `projectId`, `workspaceId`
- `journeyId`, `stepId`, `domain`
- `actorRole`, `outcome`, `latencyMs`
- `errorCode` (when applicable)

## 5. Acceptance Criteria (OST-00003)

`OST-00003` is complete only when all criteria below are true:

1. At least five primary Studio journeys are documented end-to-end.
2. Journey steps explicitly traverse relevant domain surfaces.
3. At least ten critical edge cases are documented with deterministic required
   behavior.
4. Journey-to-surface mapping is defined for top-level Studio IA.
5. Instrumentation requirements are defined for journey observability.
6. Content is aligned to ADR-0007 context model and dependency map.
