# OSHUN Studio Navigation and Command Surfaces Runbook

Status: Active  
Owner: OSHUN Studio Product Design + OSHUN Web  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0020-oshun-studio-navigation-and-command-surfaces.md`
- `docs/releases/v1/specs/studio-navigation-and-command-surfaces-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-navigation-and-command-surfaces-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioNavigationCommandWorkspace.tsx`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio navigation and command-surface governance workflows.

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

## 1. Ownership Model

| Surface                               | Primary Owner          | Backup Owner        | Dependencies                  |
| ------------------------------------- | ---------------------- | ------------------- | ----------------------------- |
| Navigation/command workspace route    | OSHUN Web              | Platform Web        | route + analytics contracts   |
| Route contracts and context hydration | Navigation Platform    | Web Platform        | `libs/oshun/navigation`       |
| Command catalog governance            | Product Design + Web   | Domain Integrations | command registry contracts    |
| Policy enforcement                    | Security + Product Ops | Platform Identity   | entitlement/session payloads  |
| Telemetry and audit pipeline          | Data Platform          | SRE                 | sinks and ingestion pipelines |

## 2. Core SLOs

| Metric                                    | Target             | Alert Threshold      |
| ----------------------------------------- | ------------------ | -------------------- |
| Navigation/command flow success rate      | >= 99.0%           | < 98.0% over 15 min  |
| Route context validation integrity        | 100% deterministic | any false pass       |
| Cross-domain navigation sync success rate | >= 99.5%           | < 99.0% over 15 min  |
| Navigation/command flow p95 latency       | <= 2200ms          | > 3200ms over 15 min |
| Navigation/command audit completeness     | >= 99.5%           | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Command Catalog Publish Failures

Trigger: repeated `COMMAND_SCOPE_METADATA_INVALID` outcomes.

Actions:

1. Inspect command metadata and scope contract diagnostics.
2. Validate command IDs, categories, and policy bindings.
3. Re-run publish in preview with diagnostics enabled.
4. Roll back to last certified command catalog if needed.

### 3.2 Route Context Validation Failures

Trigger: repeated `ROUTE_CONTEXT_VALIDATION_FAILED` outcomes.

Actions:

1. Identify failing context keys, back-stack, or fallback behaviors.
2. Validate route contract compatibility and hydration logic.
3. Apply route/context fixes.
4. Re-run validation and block promotion until pass.

### 3.3 Cross-Domain Navigation Drift

Trigger: `CROSS_DOMAIN_NAVIGATION_DRIFT` findings.

Actions:

1. Generate drift report by domain and route/command mapping.
2. Re-apply canonical navigation and command contracts.
3. Re-run sync and parity checks.
4. Freeze release channel promotion until drift is resolved.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare command policy map against entitlement contracts.
2. Verify identity payload/version changes from upstream.
3. Apply policy hotfix or rollback entitlement drift.
4. Confirm denial rates normalize post-mitigation.

### 3.5 Telemetry and Audit Degradation

Trigger: missing or delayed navigation/command telemetry events.

Actions:

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

## 4. Release Checklist

- [ ] Validate `/studio/navigation-commands` renders and executes all 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 Navigation/Command Incident
Detected: {timestamp}
Impact: {catalog/route/sync impact}
Suspected cause: {scope metadata issue | context validation regression | navigation drift | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Navigation/Command Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {commandCatalogPublish | routeContextValidation | crossDomainNavigationSync}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Navigation/Command 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             |
| Route contracts and navigation | `#oshun-navigation`     | Navigation architecture lead |
| Command policy and governance  | `#oshun-security`       | Security lead                |
| Domain integration             | `#project-obsidian-ops` | Domain integration lead      |
| Telemetry pipeline             | `#oshun-data-platform`  | SRE lead                     |

## 7. Acceptance Criteria (OST-00064)

`OST-00064` is complete only when:

1. Ownership and decision authority are documented.
2. Navigation/command 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.
