Status: Active
Owner: OSHUN Studio Product + UX Architecture
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0013-oshun-studio-information-architecture.mddocs/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#
- Preserve context (
programId,projectId,workspaceId) at all times. - Keep critical workflows executable in <= 5 major steps.
- Surface system state continuously for long-running operations.
- Allow optimistic progress with explicit rollback and recovery paths.
- 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:
- Create program (
ProgramContext) with governance template. - Create/attach projects and workspaces in Yemaya.
- Attach world canon root in Hathor.
- Configure generation defaults and cost controls in Isis.
- Configure motion standards in Aja.
- Configure build/export targets in Bellona.
- Publish execution dashboard and initial release gates.
Success State:
- Program dashboard shows all attached projects/domains.
- Baseline release gates are
pendingwith 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:
- Edit world/narrative in Hathor and pass lore validation.
- Trigger generation package in Isis using world constraints.
- Trigger motion package in Aja for associated scene/performance needs.
- Review outputs in Yemaya asset review queue.
- Trigger Bellona build/export for selected engine/platform targets.
- Inspect artifacts, diagnostics, and quality outcomes.
- 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
pendingtoin_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:
- Clone previous workflow/version/branch.
- Apply targeted edits (prompt/constraint/animation/world state).
- Execute isolated job with scoped resources and priority.
- Compare outputs side-by-side with quality metrics.
- 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:
- Open review package for milestone/asset/build.
- Gather comments, annotations, and required changes.
- Route to assigned approvers by role.
- Resolve findings and re-submit package.
- 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:
- Surface degraded dependency and impacted workflows.
- Offer fallback choices (retry, queue, alternate provider/path).
- Preserve queued intent and context.
- Resume operation automatically on dependency recovery.
- 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.startedjourney.step.completedjourney.blockedjourney.recoveredjourney.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,domainactorRole,outcome,latencyMserrorCode(when applicable)
5. Acceptance Criteria (OST-00003)#
OST-00003 is complete only when all criteria below are true:
- At least five primary Studio journeys are documented end-to-end.
- Journey steps explicitly traverse relevant domain surfaces.
- At least ten critical edge cases are documented with deterministic required behavior.
- Journey-to-surface mapping is defined for top-level Studio IA.
- Instrumentation requirements are defined for journey observability.
- Content is aligned to ADR-0007 context model and dependency map.