Eve library

OSHUN Studio SDK and Documentation Integration Runbook

Runbook

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Developer Experience + OSHUN Security + Platform SRE + OSHUN Data/Analytics Engineering + Program Operations
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0048-oshun-studio-sdk-and-documentation-integration.md
  • docs/releases/v1/specs/studio-sdk-and-documentation-integration-dependency-and-data-contract-map.md
  • docs/releases/v1/specs/studio-sdk-and-documentation-integration-user-journeys-and-edge-cases.md
  • apps/oshun/web/src/components/studio/StudioSdkDocumentationIntegrationWorkspace.tsx
  • apps/oshun/web/src/analytics/studioSdkDocumentationIntegrationTelemetry.ts

Purpose#

Define operational ownership, SLOs, incident playbooks, and escalation paths for Studio SDK and documentation integration workflows.

This document is the execution artifact for OST-00288.

1. Ownership Model#

Surface Primary Owner Backup Owner Dependencies
SDK/docs integration workspace route OSHUN Web Platform Web workflow UX orchestration + release visibility
Contract source registry and lifecycle OSHUN BFF + Studio Architecture Platform SRE contract schemas + digest/version governance
SDK generation and package publication Developer Experience BFF platform codegen pipelines + artifact registries
Documentation assembly and publication Developer Experience + Web Program Operations API reference/guides/samples + publication channels
Policy/approval controls for sensitive actions Security + Compliance Program Operations role/tier governance + CAB evidence
Telemetry and governance audit continuity Data Platform + Security Platform SRE analytics sinks + retention/export controls + replay path

2. Core SLOs#

Metric Target Alert Threshold
SDK/docs integration flow success rate >= 99.0% < 98.0% over 15 min
Contract-to-artifact consistency >= 99.5% < 99.0% over 15 min
Generation/publication/recovery flow p95 <= 2500ms > 3500ms over 15 min
Sample-validation pass continuity >= 99.5% < 99.0% over 15 min
Policy-tier/CAB enforcement correctness >= 99.5% < 99.0% over 15 min
Drift incident closure determinism >= 99.5% < 99.0% over 15 min
Telemetry/audit event delivery continuity >= 99.5% < 99.0% over 15 min

3. Operational Playbooks#

3.1 Contract Promotion Failures#

Trigger: repeated SDK_DOCS_CONTRACT_PROMOTION_FAILED outcomes.

Actions:

  1. Validate contract identity (contractId, version, digest, lifecycle).
  2. Inspect compatibility checks and migration guidance artifacts.
  3. Re-run promotion in preview with diagnostics enabled.
  4. Block downstream SDK/docs publication until contract integrity recovers.

3.2 SDK Generation or Publication Failures#

Trigger: repeated SDK_DOCS_SDK_GENERATION_FAILED outcomes.

Actions:

  1. Validate codegen input contract and target language profile.
  2. Inspect compile/type-test failures and package metadata drift.
  3. Re-run generation against known-good toolchain baseline.
  4. Escalate to Developer Experience on sustained generation regressions.

3.3 Documentation Publication Failures#

Trigger: repeated SDK_DOCS_DOCUMENTATION_PUBLISH_FAILED outcomes.

Actions:

  1. Validate reference/guides/sample bundle completeness.
  2. Inspect publish-channel health and release metadata integrity.
  3. Re-run publication after dependency verification.
  4. Preserve release hold until documentation integrity is restored.

3.4 Sample Validation Drift#

Trigger: repeated SDK_DOCS_SAMPLE_VALIDATION_FAILED outcomes.

Actions:

  1. Validate sample bindings against active contract and SDK versions.
  2. Inspect runtime fixture drift and stale snippet dependencies.
  3. Re-run sample validation across target language/runtime profiles.
  4. Block promotion to production until sample parity recovers.

3.5 Sensitive Publish/Rollback Policy Failures#

Trigger: repeated SDK_DOCS_POLICY_DECISION_FAILED outcomes.

Actions:

  1. Validate role/tier/CAB prerequisites and reason codes.
  2. Inspect policy bundle drift and deny-path anomalies.
  3. Re-run decision with compliance-auditor oversight.
  4. Freeze production publish/rollback path while policy integrity is degraded.

3.6 SDK/Docs Consistency Recovery Failures#

Trigger: repeated SDK_DOCS_CONSISTENCY_RECOVERY_FAILED outcomes.

Actions:

  1. Validate incident-state and remediation-action preconditions.
  2. Verify post-remediation SDK/docs/contract alignment checks.
  3. Re-run recovery flow under incident command oversight.
  4. Prevent incident closure until deterministic revalidation is complete.

3.7 Telemetry and Audit Degradation#

Trigger: missing or delayed studio_sdk_documentation_integration_* telemetry events.

Actions:

  1. Validate analytics sink health and ingestion backlog.
  2. Enable degraded-observability notice in SDK/docs workspace.
  3. Replay buffered events where replay semantics are supported.
  4. Confirm SLO panel and audit-evidence continuity after recovery.

4. Release Checklist#

  • Validate /studio/sdk-documentation-integration renders and executes required flows.
  • Validate optimistic, error, and retry behavior across all SDK/docs integration flows.
  • Validate permission-tier and production CAB policy enforcement.
  • Validate telemetry/audit emissions and SLO panel updates.
  • Validate integration/e2e/accessibility/performance evidence artifacts.

5. Incident Communication Templates#

Incident Start#

text
[P{severity}] Studio SDK/Docs Integration Incident
Detected: {timestamp}
Impact: {contract-promotion | sdk-generation | docs-publication | policy-decision | consistency-recovery}
Suspected cause: {contract drift | toolchain regression | policy drift | sample validation drift | telemetry degradation}
Owner: {on-call}

Incident Update#

text
[P{severity}] Studio SDK/Docs Integration Update
Time: {timestamp}
Mitigation: {rollback | hotfix | policy patch | republish | release hold}
Affected flows: {promoteContractVersion | generateSdkArtifact | publishDocumentationRelease | decideSensitivePublishRollback | recoverSdkDocsConsistency}
ETA: {time}

Incident Resolved#

text
[P{severity}] Studio SDK/Docs Integration 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
SDK/docs integration workspace UX #oshun-web Platform on-call
Contract registry and codegen APIs #oshun-bff BFF lead
SDK generation and package publication #oshun-developer-exp DX lead
Policy-tier/CAB governance controls #oshun-security Security + Compliance
Telemetry and audit reporting continuity #oshun-data-platform Data platform lead

7. Acceptance Criteria (OST-00288)#

OST-00288 is complete only when:

  1. Ownership and decision authority are documented.
  2. SDK/docs integration 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.