Eve library

OSHUN Studio Spacing/Layout Runbook

Runbook

Revision 1

On this page

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#

text
[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#

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

Incident Resolved#

text
[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.