Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + Platform SRE + OSHUN
Data/Analytics Engineering
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.mddocs/releases/v1/specs/studio-observability-and-operational-dashboards-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio observability and operational dashboard workflows.
This document is the execution artifact for OST-00227.
Personas#
- Program Operator
- Collaboration Lead
- Platform SRE
- Security Reviewer
- Compliance Auditor
Journey Principles#
- Every operational signal must map to canonical SLI/SLO semantics.
- Alert triage must preserve full domain/workflow/ownership attribution.
- Remediation actions must enforce role, permission-tier, and release policy.
- Dashboard actions must emit telemetry and audit records deterministically.
1. Primary Journeys#
J1. Monitor Cross-Domain Operational Health#
Goal: View Studio-wide SLI/SLO posture across Yemaya, Isis, Hathor, Aja, Bellona, and OSHUN control surfaces.
Entry: Observability and operational dashboards workspace
Steps:
- Load dashboard signal cards by domain and window.
- Review status (
healthy,warning,degraded,critical) and trend indicators. - Compare current values vs SLO targets.
- Identify highest-impact breached signals.
- Persist operational snapshot for shift handoff.
Success State:
- Operator can prioritize the top risks using one canonical dashboard view.
J2. Drill Down from Signal to Dependency Root Cause#
Goal: Isolate likely root cause from a degraded signal card.
Entry: Dashboard signal card in warning/degraded/critical state
Steps:
- Open signal drill-down panel.
- Review workflow identity, source domain, and dependency graph.
- Inspect upstream/downstream impact and correlated alerts.
- Open trace/evidence references for the selected window.
- Produce root-cause hypothesis for triage action.
Success State:
- Incident hypothesis is generated with attributable dependency evidence.
J3. Execute Policy-Aware Remediation Action#
Goal: Trigger safe remediation from dashboard context.
Entry: Alert/incident card requiring intervention
Steps:
- Select remediation action (retry, rollback, gate hold, escalation).
- Validate role and permission-tier eligibility.
- Supply CAB approval ticket for production-impacting actions.
- Execute remediation and track action status.
- Emit remediation audit evidence linked to alert and signal.
Success State:
- Remediation executes only when policy constraints are satisfied.
J4. Drive Alert Lifecycle to Resolution#
Goal: Move alerts through deterministic triage states.
Entry: Active alert queue
Steps:
- Acknowledge alert and assign an owner.
- Transition state to investigating with contextual notes.
- Record remediation and verification evidence.
- Resolve and close alert once SLO/signal posture stabilizes.
- Export closure evidence for governance reporting.
Success State:
- Alert lifecycle is complete with deterministic state transitions and evidence.
J5. Evaluate Operational Readiness for Release#
Goal: Gate production promotion on operational readiness.
Entry: Release checkpoint in Project Obsidian control flow
Steps:
- Evaluate SLO rollup snapshot for all participating domains.
- Validate telemetry freshness and completeness indicators.
- Confirm no unresolved critical alerts or policy violations.
- Approve or block release with explicit reason codes.
- Emit release-readiness decision event with attribution.
Success State:
- Release decision is deterministic, auditable, and evidence-backed.
2. Critical Edge Cases#
E1. Signal Card Staleness#
- Trigger:
updatedAtexceeds freshness window. - Required behavior: mark signal stale/degraded and block readiness decisions.
E2. Missing SLO Target#
- Trigger: signal card has no target value.
- Required behavior: quarantine card and raise configuration defect alert.
E3. Domain Not in Registry#
- Trigger: signal source domain absent from canonical domain registry.
- Required behavior: block drill-down and emit domain-mapping violation event.
E4. Orphaned Alert Without Signal Link#
- Trigger: alert exists without
signalId. - Required behavior: block state transitions and route to data-quality queue.
E5. Invalid Alert State Transition#
- Trigger: attempted transition skips lifecycle rules (for example,
new -> resolved). - Required behavior: deny transition and emit policy violation audit event.
E6. Remediation Action Without Permission Tier#
- Trigger: action requested without valid permission-tier context.
- Required behavior: deny action and require explicit tier selection.
E7. Production Remediation Without CAB Ticket#
- Trigger: production-impacting action has missing/invalid CAB evidence.
- Required behavior: hard deny action and emit approval-policy denial event.
E8. Drill-Down Dependency Graph Timeout#
- Trigger: dependency graph query exceeds timeout budget.
- Required behavior: show partial graph + fallback diagnostics + retry action.
E9. Conflicting Concurrent Alert Updates#
- Trigger: two operators mutate the same alert lifecycle simultaneously.
- Required behavior: enforce optimistic concurrency and preserve causal order.
E10. Release-Gate Decision Without Telemetry Completeness#
- Trigger: readiness gate executed with low telemetry completeness score.
- Required behavior: auto-block release and emit readiness-quality denial.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Monitor Operational Health | Observability/operational dashboards | Metrics instrumentation + SLO rollup feeds |
| J2 Drill Down to Root Cause | Dashboard drill-down panels | Domain dependency graph + trace services |
| J3 Execute Policy-Aware Remediation | Dashboard action panel | RBAC/policy engine + CAB governance |
| J4 Drive Alert Lifecycle to Resolution | Dashboard alert queue | Incident routing + governance exports |
| J5 Evaluate Operational Release Readout | Dashboard readiness gate panel | Release orchestration + quality services |
4. Instrumentation Requirements#
Required events:
observability_dashboards.journey.startedobservability_dashboards.journey.step.completedobservability_dashboards.journey.blockedobservability_dashboards.journey.recoveredobservability_dashboards.journey.completed
Required dimensions:
signalId,alertId,sourceDomain,workflowId,dependencyRefactorId,actorRole,permissionTier,workspaceId,releaseChanneljourneyId,stepId,outcome,latencyMs,errorCode,reasonCodesloTarget,sloActual,telemetryCompletenessRate,approvalTicketRef
5. Acceptance Criteria (OST-00227)#
OST-00227 is complete only when:
- At least five observability/dashboard journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.