Eve library

OSHUN Studio Internationalization and Localization Runbook

Runbook

Revision 1

On this page

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

  • docs/adr/ADR-0045-oshun-studio-internationalization-and-localization.md
  • docs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.md
  • docs/releases/v1/specs/studio-internationalization-and-localization-user-journeys-and-edge-cases.md
  • apps/oshun/web/src/components/studio/StudioInternationalizationLocalizationWorkspace.tsx
  • apps/oshun/web/src/analytics/studioInternationalizationLocalizationTelemetry.ts

Purpose#

Define operational ownership, SLOs, incident playbooks, and escalation paths for Studio internationalization and localization governance workflows.

This document is the execution artifact for OST-00264.

1. Ownership Model#

Surface Primary Owner Backup Owner Dependencies
i18n/l10n governance workspace route OSHUN Web Platform Web route contracts + governance UX orchestration
Locale catalog lifecycle and ownership OSHUN BFF + Domain teams Platform SRE catalog schemas + ownership/version governance
Localization validation and runtime monitoring Platform SRE + Web QA Data Platform coverage/RTL/expansion suites + runtime fallback probes
Waiver/block policy and approval controls Security + Compliance Program Operations role/tier policy bundles + CAB governance
Remediation execution and closure workflows Web + Platform SRE Domain integrators issue-state transitions + post-fix validation reruns
Telemetry and audit evidence continuity Data Platform + Security Platform SRE analytics sinks + retention/export controls + replay safety

2. Core SLOs#

Metric Target Alert Threshold
Localization governance flow success rate >= 99.0% < 98.0% over 15 min
Locale catalog integrity >= 99.5% < 99.0% over 15 min
Validation/monitoring/remediation flow p95 <= 2500ms > 3500ms over 15 min
Runtime fallback posture signal continuity >= 99.5% < 99.0% over 15 min
Policy-tier/CAB enforcement correctness >= 99.5% < 99.0% over 15 min
Critical localization issue 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 Locale Catalog Publish Failures#

Trigger: repeated LOCALIZATION_CATALOG_PUBLISH_FAILED outcomes.

Actions:

  1. Validate catalog identity (catalogId, locale, namespace, version) and ownership metadata.
  2. Inspect catalog schema compatibility and contract version drift.
  3. Re-run publish in preview channel with validation diagnostics enabled.
  4. Block production waiver/remediation actions until catalog integrity recovers.

3.2 Localization Validation Failures#

Trigger: repeated LOCALIZATION_VALIDATION_SUITE_FAILED outcomes.

Actions:

  1. Validate failing coverage/RTL/expansion evidence artifacts.
  2. Inspect validation harness drift, flaky suites, and stale fixtures.
  3. Re-run localization validation against known-good baseline snapshots.
  4. Maintain release block while critical localization failures remain unresolved.

3.3 Runtime Formatting/Fallback Degradation#

Trigger: repeated LOCALIZATION_RUNTIME_MONITORING_FAILED outcomes.

Actions:

  1. Validate runtime telemetry ingestion and locale-catalog binding identity.
  2. Inspect fallback-rate spikes and delayed formatter signal streams.
  3. Re-run runtime posture checks with bounded diagnostic windows.
  4. Escalate to Platform SRE for sustained critical locale degradation.

3.4 Waiver/Block Decision Failures#

Trigger: repeated LOCALIZATION_POLICY_DECISION_FAILED outcomes.

Actions:

  1. Validate role/tier/CAB prerequisites and denial reason codes.
  2. Inspect policy bundle drift and production-governance anomalies.
  3. Re-run waiver/block decisions with compliance auditor supervision.
  4. Freeze production promotions while decision integrity is degraded.

3.5 Remediation Closure Failures#

Trigger: repeated LOCALIZATION_REMEDIATION_CLOSURE_FAILED outcomes.

Actions:

  1. Validate issue-state and remediation-action preconditions.
  2. Verify post-fix localization validation pass evidence before closure.
  3. Re-run remediation closure under incident command oversight.
  4. Prevent issue closure until deterministic revalidation is complete.

3.6 Policy Denial Spike#

Trigger: sustained increase in ROLE_POLICY_DENIED, PERMISSION_TIER_ROLE_DENIED, FLOW_PERMISSION_TIER_INSUFFICIENT, POLICY_JUSTIFICATION_REQUIRED, PRODUCTION_APPROVAL_REQUIRED, or PRODUCTION_WAIVER_REQUIRES_COMPLIANCE_AUDITOR.

Actions:

  1. Compare active role/tier/CAB policy bundles against intended controls.
  2. Inspect recent policy releases for deny-path regressions.
  3. Roll back or patch policy bundle and revalidate all decision paths.
  4. Confirm denial-rate normalization across localization governance flows.

3.7 Telemetry and Audit Degradation#

Trigger: missing or delayed studio_internationalization_localization_* telemetry events.

Actions:

  1. Validate analytics sink health and ingestion backlog.
  2. Enable degraded-observability notice in localization 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/internationalization-localization renders and executes required flows.
  • Validate optimistic, error, and retry behavior for all localization governance 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 Localization Governance Incident
Detected: {timestamp}
Impact: {catalog-publish | validation-suite | runtime-monitoring | waiver-block | remediation-closure}
Suspected cause: {policy drift | schema regression | telemetry degradation | localization regression}
Owner: {on-call}

Incident Update#

text
[P{severity}] Studio Localization Governance Update
Time: {timestamp}
Mitigation: {rollback | hotfix | policy patch | release hold}
Affected flows: {publishLocalizationCatalog | runLocalizationValidationSuite | monitorRuntimeFormattingFallbacks | decideLocalizationWaiverOrBlock | executeLocalizationRemediationClosure}
ETA: {time}

Incident Resolved#

text
[P{severity}] Studio Localization Governance 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
Localization governance workspace UX #oshun-web Platform on-call
Locale catalogs and validation APIs #oshun-bff BFF lead
Runtime fallback and formatter telemetry #oshun-platform-sre SRE lead
Policy-tier/CAB governance controls #oshun-security Security + Compliance
Localization analytics and audit reporting #oshun-data-platform Data platform lead

7. Acceptance Criteria (OST-00264)#

OST-00264 is complete only when:

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