{
  "id": "page:library-incident-management",
  "_kind": "Page",
  "_file": "wiki/library/incident-management.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Incident Management (Library)",
    "displayName": "Incident Management (Library)",
    "slug": "library/incident-management",
    "articlePath": "wiki/library/incident-management.md",
    "article": "\n# Incident Management\n\nSingle owner for incident handling across the library. This specialization carries the flagship detection-to-postmortem lifecycle — severity classification, commander mobilization, parallel mitigation strands, severity-routed policy gates for every externally visible action, an adversarial postmortem-completeness gate, and kip-backed incident memory across runs.\n\n## Consolidation statement\n\nThe library census flagged three scattered near-misses that each owned a slice of incident handling. This specialization consolidates them under one flagship process:\n\n- **Supersedes** [`specializations/devops-sre-platform/incident-response.js`](../devops-sre-platform/incident-response.js) — **deprecated, do not extend.** Harvested: commander/roles mobilization, parallel log/metrics/trace investigation (folded into the diagnosis strand), blast-radius fields, MTTR/MTTD metrics, Style-A task shape.\n- **Supersedes** [`specializations/domains/business/customer-experience/itil-incident-management.js`](../domains/business/customer-experience/itil-incident-management.js) — **deprecated, do not extend.** Harvested: categorization-informed severity rationale; the knowledge-base lookup is replaced by `kipRecall`, the post-incident-review loop by `adversarialGate`.\n- **Absorbs** [`specializations/observability/incident-lifecycle.js`](../observability/incident-lifecycle.js) — structural seed: single-workflow lifecycle, severity matrix text, non-incident early exit, timeline accumulation, comms phase model with no-blame rules, iterative 3-pass diagnosis, SLO breach detection, follow-up issue creation.\n\nThe superseded files are **not deleted** by this consolidation — this README declares them deprecated pending a separate removal pass. New work goes here.\n\n## Migration notes\n\n| Old process | Old inputs | New inputs mapping | Behavioral deltas |\n|---|---|---|---|\n| `devops-sre-platform/incident-response` | `{ incidentType, severity, affectedServices, alertSource, description }` | `signal: { source: alertSource, ref, firstSeenAt, symptomSummary: description, impactedSurfaces: affectedServices }` + `severityOverride: severity` | Severity is classified by the process (the old hand-fed `severity` becomes `severityOverride`, which wins and is recorded in metadata). Production changes and all comms now sit behind severity-routed policy gates instead of running unguarded. |\n| `business/customer-experience/itil-incident-management` | `{ incident, knowledgeBase }` | `incident` fields fold into `signal{...}`; `knowledgeBase` is replaced by the kip store (`kipEnabled`/`kipDir`/`kipModel`) | KB lookup becomes `kipRecall` at detection; the post-incident-review loop becomes the adversarial postmortem-completeness gate with executed evidence. |\n| `observability/incident-lifecycle` | `{ signal, onCall, commsChannels, slo }` | Same shape — `onCall` becomes `oncall` (adds `commsLead`, `engineeringManager`); adds `severityOverride`, `customerFacing`, `postmortemRequired`, kip knobs | Comms no longer publish directly: every status-page/customer message rides a policy gate. Postmortem gains the adversarial completeness gate and gated publication. |\n\n## Module table — `incident-lifecycle.js` exports\n\n| Export | Kind | Purpose |\n|---|---|---|\n| `process(inputs, ctx)` | orchestrator | The flagship lifecycle, phases P0–P10 |\n| `SEVERITY_ROUTING` | frozen const | Policy-gate expert routing per severity (lookup via `routingExpert`) |\n| `COMMS_CADENCE` | frozen const | Comms cadence rules per severity |\n| `REQUIRED_ROLES` | frozen const | Roles that must be staffed per severity |\n| `INCIDENT_SEVERITIES` | frozen const | `['SEV1','SEV2','SEV3','SEV4']` |\n| `routingExpert(actionId, severity)` | helper | Routing lookup — **throws** on unknown action, unknown severity, or never-raised actions (no fallback expert) |\n| `commsPolicyFor(actionId, severity, customerFacing)` | helper | Cadence-table lookup — **throws** on unknown severity/action |\n| `detectClassifyTask` | agent task | `iml.detect-classify` — severity classification |\n| `commanderAssignmentTask` | agent task | `iml.commander-assignment` — roster mobilization |\n| `diagnoseTask` | agent task | `iml.diagnose` — iterative root-cause passes |\n| `blastRadiusTask` | agent task | `iml.blast-radius` — impact assessment |\n| `commsDraftTask` | agent task | `iml.comms-draft` — drafts only, never publishes |\n| `mitigationPlanTask` | agent task | `iml.mitigation-plan` — reversible-first plan |\n| `executeMitigationTask` | agent task | `iml.execute-mitigation` — only after its gate approves |\n| `publishCommsTask` | agent task | `iml.publish-comms` — only after its gate approves |\n| `verifyRecoveryTask` | agent task | `iml.verify-recovery` — executed probe evidence |\n| `postmortemDraftTask` | agent task | `iml.postmortem-draft` — blameless postmortem markdown |\n| `actionItemTrackingTask` | agent task | `iml.action-item-tracking` — one issue per action item |\n\nAll tasks are Style-A `kind: 'agent'` (zero `kind: 'shell'`), with per-effect `io` paths and `labels`, and every evidence-carrying output schema declares `evidence { type: 'array', minItems: 1 }`. Gate combinators (`routedBreakpoint`, `adversarialGate`, `kipRecall`, `kipAssert`) are imported from [`../common-utilities/routed-gate-combinators.js`](../common-utilities/routed-gate-combinators.js), not redefined.\n\n## Severity model\n\n- **SEV1** — user-facing outage on a critical path OR data loss/corruption risk.\n- **SEV2** — significant degradation with ongoing user impact (workaround may exist).\n- **SEV3** — partial degradation, limited user impact.\n- **SEV4** — internal-only, no user impact, cleanup-later.\n- **non-incident** — false alarm, duplicate, or expected behavior → early return before any commander is assigned or gate raised.\n\n### Routing table (`SEVERITY_ROUTING`, verbatim)\n\n| Action | SEV1 | SEV2 | SEV3 | SEV4 |\n|---|---|---|---|---|\n| `execute-prod-mitigation` | incident-commander | incident-commander | tech-lead | tech-lead |\n| `publish-status-page` | comms-lead | comms-lead | comms-lead (presentAlwaysApprove) | not raised |\n| `send-customer-incident-comms` | comms-lead | comms-lead (only if customerFacing) | not raised | not raised |\n| `publish-postmortem` | engineering-manager | engineering-manager | tech-lead | tech-lead (postmortem only when postmortemRequired===true) |\n\n### Comms cadence table (`COMMS_CADENCE`, verbatim)\n\n| Severity | Status page | Customer comms |\n|---|---|---|\n| SEV1 | required, 30m updates | required |\n| SEV2 | required, 60m updates | required iff customerFacing |\n| SEV3 | discretionary | not required |\n| SEV4 | not required | not required |\n\nLookups go through `routingExpert(actionId, severity)`, which **throws** on an unknown severity, an unknown action, or an action that is never raised at that severity. There is deliberately no default expert — fallbacks are forbidden.\n\n## Policy-gated actions\n\nFour actions are policy-gated. Convention: **`breakpointId` = actionId**, tags `['policy-gated', 'incident', '<sev>']` (severity tag interpolated per run), strategy `single`, expert from `SEVERITY_ROUTING`.\n\n| actionId | What it gates | Raised when |\n|---|---|---|\n| `execute-prod-mitigation` | Any production change made to mitigate the incident (config change, rollback, failover, feature-flag kill) | Always, before any production change. Never auto-approves (`autoApproveAfterN` is never set). Rejection → one re-plan pass; second rejection ends the run `success:false` with the executor never invoked. |\n| `publish-status-page` | Publishing/updating the public status page entry | SEV1/SEV2 required; SEV3 discretionary (`presentAlwaysApprove:true`); SEV4 never |\n| `send-customer-incident-comms` | Direct customer notifications about impact, workarounds, or resolution | SEV1 required; SEV2 required iff `customerFacing`; SEV3/SEV4 never |\n| `publish-postmortem` | Publishing the blameless postmortem to its audience | Only after the adversarial completeness gate passes (or the owner accepts via escalation) |\n\n**Fail-closed posture:** a rejected or never-raised gate leaves its action unexecuted and unpublished — there is no alternate path around a gate. Every not-raised comms action is still recorded in `commsLog` as `{ required: false, raised: false }`. Any harness-level auto-approval of a gate is surfaced in `outputs.autoApprovals` (`{ breakpointId, phase, at }`), which is **always present** in outputs, possibly empty.\n\nThe only non-policy breakpoint is `iml.commander-assignment.roster-gap`, raised solely when severity-required roles are unstaffed (sparse-breakpoint rule: an unstaffed incident is genuinely blocking).\n\n## Quality gate — postmortem completeness\n\n`adversarialGate(ctx, { gateId: 'iml.postmortem-completeness', ... })` fans out three independent critics over the postmortem draft (the postmortem author never reviews its own work):\n\n| Critic | Focus |\n|---|---|\n| `timeline-fidelity-critic` | Every timeline entry in the postmortem matches the run journal and task timestamps — the comparison is EXECUTED (read both, diff them), with each verified/mismatched entry cited. The orchestrator accumulates the timeline itself, so the critic has ground truth to diff. |\n| `action-item-completeness-critic` | Every action item has a named owner AND concrete due date AND category; every \"what went poorly\" finding maps to at least one action item — exact lines cited. |\n| `blameless-depth-critic` | Contributing factors go beyond the proximate cause (systemic depth, 5-whys); language blameless; root cause stated with supporting evidence. |\n\nIRON-LAW rules (appended to every critic prompt): executed evidence only — run the actual cross-checks, a read-only skim is not evidence; cite `file:line` or executed-check output for every claim; `passed:true` with empty evidence is rejected by the combinator. Fix budget: `maxFixAttempts` (default 2) rounds of the default `gateFixerTask` between critic rounds; on exhaustion the combinator escalates to the owner via a routed breakpoint (`iml.postmortem-completeness.gate-escalation`).\n\n## kip incident memory\n\n- **Recall at detection (P0)**: `kipRecall(ctx, { kipDir, topic: 'incident signature: <symptomSummary> [<impactedSurfaces>]', kipModel, kind: 'incident-management' })` — prior incidents with matching signatures, known-good mitigations, and prior action-item outcomes are threaded into classification, diagnosis, and mitigation prompts. An empty store is initialized and reported as `factCount: 0`, never an error.\n- **Assert at close (P10)**, fact shapes:\n  - `{ subject: 'incident:<incidentId>', predicate: 'has-signature', object: <signatureString> }`\n  - `{ subject: 'incident:<incidentId>', predicate: 'root-cause', object: <rootCause> }`\n  - `{ subject: 'incident:<incidentId>', predicate: 'mitigated-by', object: <planSummary>, props: { efficacy: 'effective'|'ineffective', reversible } }`\n  - one per action item: `{ subject: 'incident:<incidentId>', predicate: 'action-item', object: <title>, props: { owner, dueDate, category } }`\n\nBoth touchpoints are wrapped in `if (kipEnabled)` (default `true`); the assert facts array is built unconditionally-non-empty when reached (the signature fact always exists).\n\n## Usage\n\n```bash\nbabysitter run:create \\\n  --process-file library/specializations/incident-management/incident-lifecycle.js \\\n  --inputs '{\n    \"signal\": {\n      \"source\": \"alert\",\n      \"ref\": \"pagerduty:P-4821\",\n      \"firstSeenAt\": \"2026-07-23T09:14:00Z\",\n      \"symptomSummary\": \"checkout API p99 latency 8x baseline, elevated 5xx on payment confirmation\",\n      \"impactedSurfaces\": [\"checkout\", \"payments-api\"]\n    },\n    \"customerFacing\": true,\n    \"oncall\": {\n      \"primary\": \"alice\",\n      \"secondary\": \"bob\",\n      \"commsLead\": \"carol\",\n      \"engineeringManager\": \"dana\"\n    },\n    \"commsChannels\": [\n      { \"kind\": \"status-page\", \"target\": \"status.example.com\" },\n      { \"kind\": \"slack\", \"target\": \"#incident-war-room\" }\n    ],\n    \"slo\": { \"mttdMinutes\": 10, \"mttrMinutes\": 120 }\n  }'\n```\n\nA signal like this classifies as SEV2: the status page gate routes to `comms-lead` (required, 60m cadence), customer comms is required because `customerFacing` is true, mitigation execution routes to `incident-commander`, and postmortem publication routes to `engineering-manager` after the completeness gate passes.\n\n## Non-interactive runs\n\nNothing policy-gated auto-approves **by design** — `execute-prod-mitigation` never sets `autoApproveAfterN`, and the comms/postmortem gates require an explicit approval. If a non-interactive harness auto-approves a breakpoint at its own level, that approval is recorded in `outputs.autoApprovals` as `{ breakpointId, phase, at }` so the fail-closed posture stays auditable. `autoApprovals` is always present in outputs, even when empty.\n",
    "documents": [
      "specialization:incident-management"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-incident-management",
      "to": "specialization:incident-management",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-incident-management",
      "kind": "contains_page"
    }
  ]
}