# OSHUN Studio Spacing/Layout Runbook

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

- `docs/adr/ADR-0017-oshun-studio-spacing-and-layout-grid.md`
- `docs/releases/v1/specs/studio-spacing-layout-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-spacing-layout-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioSpacingLayoutWorkspace.tsx`

## Purpose

Define operational ownership, SLO targets, incident playbooks, and escalation
paths for Studio spacing/layout governance workflows.

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

## 1. Ownership Model

| Surface                         | Primary Owner            | Backup Owner          | Dependencies                        |
| ------------------------------- | ------------------------ | --------------------- | ----------------------------------- |
| Spacing/layout workspace route  | OSHUN Web                | Platform Web          | route contracts + analytics         |
| Spacing token bundle governance | Design Systems           | Platform Architecture | `libs/oshun/design-tokens`          |
| Density validation workflow     | Accessibility QA         | Design Systems        | density and touch-target validators |
| Grid parity synchronization     | Platform UI Architecture | Domain Integrations   | responsive layout contracts         |
| Policy enforcement              | Security + Web           | Platform Identity     | entitlement/session payloads        |
| Telemetry and audit pipeline    | Data Platform            | SRE                   | event ingestion + sink health       |

## 2. Core SLOs

| Metric                            | Target             | Alert Threshold      |
| --------------------------------- | ------------------ | -------------------- |
| Spacing/layout flow success rate  | >= 99.0%           | < 98.0% over 15 min  |
| Density validation pass integrity | 100% deterministic | any false pass       |
| Grid parity sync success rate     | >= 99.5%           | < 99.0% over 15 min  |
| Spacing/layout flow p95 latency   | <= 2200ms          | > 3200ms over 15 min |
| Spacing/layout audit completeness | >= 99.5%           | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Spacing Bundle Publish Failures

Trigger: repeated `TOKEN_USAGE_PARITY_FAILED` outcomes.

Actions:

1. Validate spacing token schema and usage parity checks.
2. Confirm bundle-version uniqueness and release metadata.
3. Execute preview publish dry-run against dependent surfaces.
4. Roll back to last certified spacing bundle if needed.

### 3.2 Density Validation Failures

Trigger: repeated `DENSITY_VALIDATION_FAILED` outcomes.

Actions:

1. Inspect failing density profiles (`compact`, `standard`, `spacious`).
2. Verify touch-target, clip, and rhythm constraints.
3. Apply targeted spacing-profile adjustments.
4. Re-run validation and hold production promotion until pass.

### 3.3 Grid Parity Drift

Trigger: `GRID_PARITY_DRIFT` findings in sync flow.

Actions:

1. Identify stale breakpoint/gutter mappings by domain.
2. Re-apply canonical layout-grid contracts.
3. Re-run parity sync and verification checks.
4. Pause release channel promotion until parity is restored.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare current UI 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 verify false-denial resolution.

### 3.5 Telemetry and Audit Degradation

Trigger: missing/delayed spacing telemetry or audit events.

Actions:

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

## 4. Release Checklist

- [ ] Validate `/studio/spacing-layout` 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 indicators.
- [ ] Validate integration/e2e/accessibility evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio Spacing/Layout Incident
Detected: {timestamp}
Impact: {publish/density/grid-parity impact}
Suspected cause: {token parity issue | density regression | grid drift | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Spacing/Layout Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {spacingBundlePublish | layoutDensityValidation | gridParitySync}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Spacing/Layout 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        |
| Spacing/layout token governance    | `#oshun-design-systems` | Architecture council    |
| Grid parity and domain integration | `#project-obsidian-ops` | Domain integration lead |
| Security and policy                | `#oshun-security`       | Security lead           |
| Telemetry pipeline health          | `#oshun-data-platform`  | SRE lead                |

## 7. Acceptance Criteria (OST-00040)

`OST-00040` is complete only when:

1. Ownership and decision authority are documented.
2. Spacing/layout SLOs and alert thresholds are documented.
3. At least five playbooks are documented for key failure modes.
4. Release checklist, communication templates, and escalation paths exist.
