Safety · Incidents and reliability

Purpose#

Declare, coordinate, mitigate, postmortem, and close incidents across reliability, safety, and compliance domains. operatorPromise: "On-call has one operator cockpit that escalates, tracks, and resolves incidents without losing timeline context."

Entry points#

• Sidebar item "Incidents" (AdminSidebar — safety group)
• Inbox → incidents handoff (inbox → incidents per OSHUN_ADMIN_WORKSPACE_RELATIONSHIPS) — "Operator opens an incident from the unified inbox."

Layout regions#

Inside AdminShell:

• <WorkspaceEntryPoint workspaceId="incidents" ...>
• When detail.accessible, four panels — each receives the same snapshot.incidentDetails:
  • <IncidentDetailPanel incidentDetails> — incident detail (the selected / active incident's full view)
  • <IncidentActionsPanel incidentDetails> — coordination actions (declare, mitigate, escalate, close)
  • <IncidentImpactCommsPanel incidentDetails> — impact assessment
    • comms drafting
  • <IncidentRunbookPostmortemPanel incidentDetails> — runbook references + postmortem authoring

snapshot is built by extractIncidentDetailSnapshot(detail.result.value).

States#

• Anonymous → middleware redirect to /unauthorized?reason=missing-session&returnTo=/incidents
• Signed-in (admin) without admin:*, admin:studio, or admin:workspace:incident → WorkspaceEntryPoint "Access not granted"; the four panels hidden
• Scope ok + BFF ok → all four panels render
• Scope ok + BFF workspace-unavailable → entry-point "Workspace data unavailable"; panels hidden
• snapshot.incidentDetails empty → each panel renders its own empty state (handled per component)
• Note bffWorkspaceId: 'incident' (singular) — IA id is incidents; the BFF endpoint is /v1/admin/workspaces/incident

Interactions#

Top-level interactive elements live inside each child panel:

• IncidentDetailPanel — current incident header / timeline / severity
• IncidentActionsPanel — declare / mitigate / escalate / close actions
• IncidentImpactCommsPanel — impact tiles + comms drafting surface (likely with templated copy)
• IncidentRunbookPostmortemPanel — runbook navigation + postmortem editor

The page itself exposes no buttons / inputs.

Data & contracts#

• Reads: loadWorkspaceDetail('incidents', session) → /v1/admin/workspaces/incident (BFF id is singular); snapshot via extractIncidentDetailSnapshot(detail.result.value) provides incidentDetails
• Writes: per panel (declare / mitigate / postmortem author); endpoints owned by each component
• Realtime: None at page level. Incident workflows are expected to be real-time-heavy but the page renders a static snapshot per nav
• Auth/role check: middleware + page (canEnterAdminWorkspace(scopes, 'incidents') → required scopes ['admin:*', 'admin:studio', 'admin:workspace:incident'])

Cross-references#

• Shell: shell/01-app-shell.md, shell/04-workspace-pattern.md
• Workspace definition: libs/oshun/navigation/src/admin-ia.ts (incidents — kind: 'investigation', operatorRelationship: 'respond', bffWorkspaceId: 'incident')
• Handoff origin (from → incidents): ../governance/inbox.md
• Handoff destinations (incidents → …): ../governance/policy.md, ../operations/analytics.md
• Library: apps/oshun/admin/src/lib/incident-detail.ts
• Component sources: IncidentDetailPanel.tsx, IncidentActionsPanel.tsx, IncidentImpactCommsPanel.tsx, IncidentRunbookPostmortemPanel.tsx

Open questions / known gaps#

• Confirm bffWorkspaceId mismatch (incidents vs incident) is intentional — pattern shows up in several workspaces
• Four panels share snapshot.incidentDetails — document whether they coordinate state via a provider or each operates on a copy
• Realtime requirement for incident timelines is implicit in the domain; verify whether the page is expected to add a subscription beyond per-nav SSR refresh