# OSHUN Studio Component Primitives Runbook

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

- `docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md`
- `docs/releases/v1/specs/studio-component-primitives-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-component-primitives-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioComponentPrimitivesWorkspace.tsx`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio component-primitives governance workflows.

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

## 1. Ownership Model

| Surface                              | Primary Owner                      | Backup Owner             | Dependencies                      |
| ------------------------------------ | ---------------------------------- | ------------------------ | --------------------------------- |
| Component-primitives workspace route | OSHUN Web                          | Platform Web             | route + analytics contracts       |
| Primitive catalog governance         | Design Systems                     | Platform UI Architecture | `libs/oshun/ui`                   |
| Composition template validation      | UX Architecture + Accessibility QA | Web Platform             | composition validators            |
| Role-policy enforcement              | Security + Web                     | Platform Identity        | entitlement/session payloads      |
| Telemetry and audit pipeline         | Data Platform                      | SRE                      | event sinks + ingestion pipelines |

## 2. Core SLOs

| Metric                               | Target             | Alert Threshold      |
| ------------------------------------ | ------------------ | -------------------- |
| Primitive flow success rate          | >= 99.0%           | < 98.0% over 15 min  |
| Composition validation integrity     | 100% deterministic | any false pass       |
| Domain primitive parity success rate | >= 99.5%           | < 99.0% over 15 min  |
| Primitive flow p95 latency           | <= 2200ms          | > 3200ms over 15 min |
| Primitive audit completeness         | >= 99.5%           | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Primitive Bundle Publish Failures

Trigger: repeated `PRIMITIVE_STATE_CONTRACT_FAILED` outcomes.

Actions:

1. Inspect primitive-state contract diagnostics by primitive and variant.
2. Verify token dependency integrity for changed primitives.
3. Re-run publish in preview with validation logging enabled.
4. Roll back to last certified primitive bundle if needed.

### 3.2 Composition Validation Failures

Trigger: repeated `COMPOSITION_TEMPLATE_FAILED` outcomes.

Actions:

1. Identify failing composition templates and interaction contracts.
2. Validate keyboard, focus order, and aria-state semantics.
3. Apply targeted composition fixes.
4. Re-run validation and block promotion until pass.

### 3.3 Domain Primitive Parity Drift

Trigger: `DOMAIN_PRIMITIVE_DRIFT` findings.

Actions:

1. Generate drift report by domain/surface.
2. Re-apply canonical primitive bundle references.
3. Re-run parity sync and verification checks.
4. Freeze release channel promotion until parity is restored.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare UI flow policy map against entitlement contracts.
2. Verify recent identity payload/version changes.
3. Apply policy hotfix or roll back entitlement drift.
4. Audit denial logs to confirm normal authorization behavior.

### 3.5 Telemetry and Audit Degradation

Trigger: missing or delayed primitive telemetry/audit events.

Actions:

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

## 4. Release Checklist

- [ ] Validate `/studio/component-primitives` 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 Component Primitives Incident
Detected: {timestamp}
Impact: {publish/composition/parity impact}
Suspected cause: {state contract issue | composition regression | parity drift | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Component Primitives Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {primitiveBundlePublish | compositionValidation | domainPrimitiveParitySync}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Component Primitives 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                       |
| Primitive catalog governance  | `#oshun-design-systems` | Architecture council                   |
| Composition and accessibility | `#oshun-product-design` | Accessibility lead                     |
| Policy and permissions        | `#oshun-security`       | Security lead                          |
| Program operations            | `#project-obsidian-ops` | Executive producer + program tech lead |

## 7. Acceptance Criteria (OST-00048)

`OST-00048` is complete only when:

1. Ownership and decision authority are documented.
2. Component-primitives 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.
