Admin Cockpit · Journey

Journey: Admin incident handling

A source-reconciled journey record for Admin Cockpit — shipped behavior, state boundaries, failure modes, and the automation evidence available today.

automated · 7 specs
9sections6 minread1table
Markdown source
On this page
Journey at a glance
ActorsIncident operatorCommunications approverPostmortem author/reviewerRead-only or out-of-scope admin
Systems exercised04-workspace-pattern.mdinbox.mdincidents.md
Automation7 E2E spec(s)

Journey flow#

Generated from the authored steps below — click a node to jump to that section.

flowchart TD s1["1. Open the incident cockpit"] s2["2. Use the guarded primary actions"] s3["3. Maintain blast radius and customer impact"] s4["4. Draft, approve, publish, and rescind commu…"] s5["5. Launch a runbook"] s6["6. Advance the postmortem"] s7["7. Resolve or cancel the incident"] s8["8. Use the unified inbox as a separate entry…"] s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 click s1 href "#1-open-the-incident-cockpit" click s2 href "#2-use-the-guarded-primary-actions" click s3 href "#3-maintain-blast-radius-and-customer-impact" click s4 href "#4-draft-approve-publish-and-rescind-communications" click s5 href "#5-launch-a-runbook" click s6 href "#6-advance-the-postmortem" click s7 href "#7-resolve-or-cancel-the-incident" click s8 href "#8-use-the-unified-inbox-as-a-separate-entry-surface"

/incidents is a real, action-capable Admin Cockpit workspace. It loads one BFF snapshot and renders incident detail, guarded mitigation/postmortem actions, blast-radius and customer-impact editors, communications, runbook launch, postmortem transitions, and closure. The unified inbox is a separate composed triage surface; this journey does not claim an unproved automatic ingestion or request-id join between them.

Incident control Admin surface
Read status, impact, timeline, tasks, comms Incident detail
Mark mitigated / publish postmortem Typed-confirmation action panel
Blast radius / customer impact Impact and communications panel
Draft / publish / rescind comms Impact and communications panel
Launch runbook / advance postmortem Runbook and postmortem panel
Resolve / cancel incident Runbook and postmortem panel
Acknowledge / assign queue items Separate inbox or operator incident APIs

Personas#

  • Incident operator — has the incident workspace scope and performs mitigations, impact updates, communications, runbook, and closure actions.
  • Communications approver — supplies approval identity when a seeded communication requires sign-off.
  • Postmortem author/reviewer — schedules, drafts, reviews, and publishes the incident record.
  • Read-only or out-of-scope admin — can enter the shell but does not receive the four incident panels.

Pre-conditions#

  • An admin session exists; otherwise /incidents redirects to the unauthorized route with a return target.
  • loadWorkspaceDetail('incidents', session) can read the BFF-backed workspace.
  • The session has the incident action scope for the interactive panels.
  • The seeded workspace includes open and resolved incidents spanning severity, communications, runbook, and postmortem states.
  • Actions run sequentially against the current incident snapshot; the browser reloads or refreshes after mutations where required.

Steps#

1. Open the incident cockpit#

  • The server page loads workspace detail and operator view, then renders WorkspaceEntryPoint.
  • An accessible workspace renders four panels: IncidentDetailPanel, IncidentActionsPanel, IncidentImpactCommsPanel, and IncidentRunbookPostmortemPanel.
  • Detail cards expose id, title, severity, status, impact scope, affected services/workspaces, update cadence, timeline, mitigation tasks, communications, and postmortem/action-item state.
  • Header counts summarize open incidents, severity, comms, overdue updates and postmortems, and action items.

2. Use the guarded primary actions#

  • Each eligible incident offers Mitigate… and Close postmortem….
  • The modal requires the incident id verbatim before Confirm becomes available.
  • Escape or Cancel closes the modal without a request.
  • Mitigate posts to /api/admin/incidents/:id/mitigate and records the mitigation in the incident timeline.
  • Close postmortem posts to the postmortem publish route and becomes unavailable after publication.
  • This panel does not expose Acknowledge, Assign to me, or Escalate. Those actions belong to separate inbox/operator incident contracts.

3. Maintain blast radius and customer impact#

  • The impact panel edits scope, affected workspaces, affected services, and rationale through the blast-radius route.
  • Client and server validation reject a short rationale.
  • The customer-impact editor records affected users and requests, error and traffic-loss percentages, revenue estimate, and summary.
  • Successful updates are visible in the incident detail and appear as distinct timeline evidence.

4. Draft, approve, publish, and rescind communications#

  • The panel lists communication audience, channel, state, content, approval requirement, author, publisher, and approver.
  • An operator can draft a new update and publish it through its state transition.
  • Approval-required communication refuses publication until an approver is supplied.
  • A published update can be rescinded only with a valid rationale.
  • The focused lifecycle covers draft → publish and published → rescinded.
  • This proves incident communication records, not delivery to every external status-page or notification adapter.

5. Launch a runbook#

  • An open incident can launch a runbook and receive a new in-progress task.
  • A resolved incident returns 409 rather than creating work.
  • Runbook activity is reflected in the snapshot counts and timeline.
  • The UI records operator workflow state; it does not automatically verify that an off-system remediation succeeded.

6. Advance the postmortem#

  • The panel enforces the explicit state machine: not_scheduled → scheduled → drafted → in_review → published.
  • Forms collect the fields required by the selected transition, including author, document reference, root cause, contributing factors, lessons, or waiver reason where applicable.
  • Invalid and already-published transitions surface named errors.
  • The orchestration spec proves scheduled and drafted state stamps in the audit timeline.

7. Resolve or cancel the incident#

  • Closure supports resolved and cancelled outcomes with the required rationale/data.
  • Sev0/sev1 resolution is blocked until at least a scheduled postmortem exists.
  • A sev1 incident with a scheduled postmortem resolves successfully.
  • A cancelled incident records its rationale.
  • Resolved cards hide mutation forms that no longer apply.

8. Use the unified inbox as a separate entry surface#

  • /inbox composes rows from incident and other workspaces, supports workspace/SLA filters and sorting, and links each row to a relative workspace detail route.
  • Its inline drawer, URL-hash round trip, selection toolbar, and bulk acknowledge behavior are independently tested.
  • The current evidence does not prove which live detector created a seeded incident, that inbox and incident mutations share one x-request-id, or that closing an incident automatically removes an inbox row.

Post-conditions#

  • Incident detail, impact, communications, runbook, postmortem, and closure state are represented in the refreshed workspace snapshot.
  • High-severity incidents cannot close without the required postmortem scheduling gate.
  • Approval-required communication cannot publish without an approver.
  • Mutations expose their resulting audit/timeline entries in the incident model.
  • Acknowledge/assign behavior, external communication delivery, global audit export, and automatic inbox ingestion are not implied by this cockpit.

Failure modes#

  • Missing session — the page redirects before workspace data renders.
  • Missing incident scope — interactive incident panels are absent.
  • Workspace unavailable — WorkspaceEntryPoint renders the backend error rather than stale action controls.
  • Wrong confirmation token — destructive action Confirm remains disabled.
  • Short rationale or invalid impact values — client/server validation rejects the mutation.
  • Approver missing — approval-required comms stay unpublished.
  • Resolved incident runbook launch — BFF returns 409.
  • Invalid postmortem transition — no state advance occurs.
  • High-severity premature closure — Sev0/Sev1 resolution returns the scheduled-postmortem gate error.
  • Stale concurrent view — the next write may be rejected by current state; the UI has no general optimistic-concurrency version documented here.
  • External delivery inferred — a published communication record is not proof that every external channel delivered it.

E2E coverage#

Coverage is deep for the dedicated incident cockpit. It does not prove live detector ingestion, cross-surface request-id correlation, external delivery, automatic inbox cleanup, or the separate operator acknowledge/assign store.

Per-view files touched by this journey#

Cross-references#

  • privileged-handoff.md — admin session entry and scope handoff.
  • ../../WALKTHROUGH/journeys/incident-triage.md — separate operator incident surface.
  • apps/oshun/admin/src/app/incidents/page.tsx — server composition.
  • apps/oshun/admin/src/components/IncidentDetailPanel.tsx — read model and timeline.
  • apps/oshun/admin/src/components/IncidentActionsPanel.tsx — typed-confirmation actions.
  • apps/oshun/admin/src/components/IncidentImpactCommsPanel.tsx — impact and communications.
  • apps/oshun/admin/src/components/IncidentRunbookPostmortemPanel.tsx — runbook, postmortem, and closure.

Open questions#

  • Which production detectors create the incident records composed here?
  • How should inbox item lifecycle track incident resolution?
  • Which idempotency or version token protects concurrent operator writes?
  • Which communication channels expose authoritative delivery receipts?
  • Should acknowledge, assign, and escalation be brought into this dedicated cockpit or remain separate operator/inbox actions?
  • Which audit explorer owns cross-incident export and correlation?