# OSHUN Studio Workspace Context Switching Runbook

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0023-oshun-studio-workspace-context-switching.md`
- `docs/releases/v1/specs/studio-workspace-context-switching-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-workspace-context-switching-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioWorkspaceContextSwitchingWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioWorkspaceContextSwitchingTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio workspace context-switching governance workflows.

This document is the execution artifact for `OST-00088`.

## 1. Ownership Model

| Surface                                    | Primary Owner                | Backup Owner       | Dependencies                        |
| ------------------------------------------ | ---------------------------- | ------------------ | ----------------------------------- |
| Workspace context-switching route          | OSHUN Web                    | Platform Web       | route + analytics contracts         |
| Context envelope and transaction contracts | Studio Architecture + BFF    | Domain Integrators | schema + policy contracts           |
| Continuity and back-stack preservation     | Navigation Platform          | Web Platform       | route context and fallback mappings |
| Role-policy and entitlement checks         | Security + Platform Identity | Ops                | identity/session payloads           |
| Telemetry and audit pipeline               | Data Platform                | SRE                | event sinks + ingestion pipelines   |

## 2. Core SLOs

| Metric                            | Target                             | Alert Threshold      |
| --------------------------------- | ---------------------------------- | -------------------- |
| Context-switch flow success rate  | >= 99.0%                           | < 98.0% over 15 min  |
| Context commit integrity          | 100% deterministic commit/rollback | any false pass       |
| Policy decision correctness       | 100% policy-consistent             | any false allow      |
| Context-switch flow p95 latency   | <= 2200ms                          | > 3200ms over 15 min |
| Context-switch audit completeness | >= 99.5%                           | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Context Switch Commit Failures

Trigger: repeated `CONTEXT_SWITCH_COMMIT_FAILED` outcomes.

Actions:

1. Inspect source/target context payload and preflight diagnostics.
2. Validate target scope availability and schema compatibility.
3. Re-run commit in preview with transaction diagnostics enabled.
4. Roll back to last certified context-switch contract if needed.

### 3.2 Continuity Preservation Failures

Trigger: repeated `CONTINUITY_VALIDATION_FAILED` outcomes.

Actions:

1. Inspect origin/back-stack continuity payload and route mapping logs.
2. Validate pending-flow hint persistence and fallback route mapping.
3. Apply continuity-mapping hotfix.
4. Re-run validation and block promotion until continuity passes.

### 3.3 Rollback Recovery Failures

Trigger: repeated `ROLLBACK_RECOVERY_FAILED` outcomes.

Actions:

1. Inspect rollback checkpoint integrity and stale-context diagnostics.
2. Rebuild last confirmed context checkpoint.
3. Re-run rollback drill in controlled preview scope.
4. Freeze release promotion until rollback recovery is deterministic.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare flow policy map against entitlement contracts.
2. Verify recent identity payload/version changes.
3. Apply policy hotfix or rollback entitlement drift.
4. Confirm deny-rate normalization after mitigation.

### 3.5 Telemetry and Audit Degradation

Trigger: missing or delayed context-switch telemetry/audit events.

Actions:

1. Validate analytics sink health and queue depth.
2. Enable degraded-observability warning in workspace.
3. Reconcile missed events from buffered traces.
4. Confirm event completeness and SLO recovery.

## 4. Release Checklist

- [ ] Validate `/studio/workspace-context-switching` renders and executes
      required flows.
- [ ] Validate optimistic, error, and retry behavior for each flow.
- [ ] Validate role-policy allow/deny behavior.
- [ ] Validate telemetry/audit emissions and SLO panel updates.
- [ ] Validate integration/e2e/accessibility evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio Workspace Context Switching Incident
Detected: {timestamp}
Impact: {commit/continuity/rollback impact}
Suspected cause: {contract regression | continuity drift | rollback failure | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Workspace Context Switching Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {contextSwitchCommit | continuityPreservationValidation | rollbackRecoveryDrill}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Workspace Context Switching Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}
```

## 6. Escalation Paths

| Area                               | Primary Channel        | Escalate To                  |
| ---------------------------------- | ---------------------- | ---------------------------- |
| Web runtime and workspace          | `#oshun-web`           | Platform on-call             |
| Context contracts and architecture | `#oshun-architecture`  | Architecture council         |
| Route continuity and navigation    | `#oshun-navigation`    | Navigation architecture lead |
| Policy and permissions             | `#oshun-security`      | Security lead                |
| Telemetry pipeline and reliability | `#oshun-data-platform` | SRE lead                     |

## 7. Acceptance Criteria (OST-00088)

`OST-00088` is complete only when:

1. Ownership and decision authority are documented.
2. Workspace context-switching SLOs and alert thresholds are documented.
3. At least five playbooks are documented for major failure modes.
4. Release checklist, communication templates, and escalation paths exist.
