Skip to content

Incident Status Workflow¤

This document describes the exact incident status workflow implemented in FireFighter.

Overview¤

The incident status workflow differs based on the incident priority:

  • P1/P2 incidents: Require post-mortem completion in PRD environment
  • P3/P4/P5 incidents: Do not require post-mortem

Workflow Diagram¤

graph TB
    subgraph "P1/P2 Incidents (PRD Environment)"
        A1[OPEN] --> B1[INVESTIGATING]
        B1 --> C1[MITIGATING]
        C1 --> D1[MITIGATED]
        D1 --> E1[POST_MORTEM]
        E1 --> F1[CLOSED]

        %% Early closure with reason
        A1 -.->|With Closure Reason| F1
        B1 -.->|With Closure Reason| F1
    end

    subgraph "P3/P4/P5 Incidents (All Environments)"
        A2[OPEN] --> B2[INVESTIGATING]
        B2 --> C2[MITIGATING]
        C2 --> D2[MITIGATED]
        D2 --> F2[CLOSED]

        %% Early closure with reason
        A2 -.->|With Closure Reason| F2
        B2 -.->|With Closure Reason| F2
    end

    %% Styling
    classDef normalPath fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff
    classDef earlyClose fill:#FF9800,stroke:#E65100,stroke-width:2px,color:#fff
    classDef postMortem fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff

    class A1,B1,C1,D1,A2,B2,C2,D2 normalPath
    class E1 postMortem
    class F1,F2 earlyClose

    linkStyle 6,7,12,13 stroke:#FF9800,stroke-width:2px,stroke-dasharray: 5 5

Legend: - 🟢 Solid arrows: Normal workflow transitions - 🟠 Dashed arrows: Early closure (requires closure reason form) - 🔵 POST_MORTEM: Mandatory for P1/P2 in PRD

Workflow Transitions¤

P1/P2 Incidents (Priority 1-2 in PRD Environment)¤

OPEN → [INVESTIGATING, CLOSED (with reason)]
INVESTIGATING → [MITIGATING, CLOSED (with reason)]
MITIGATING → [MITIGATED]
MITIGATED → [POST_MORTEM]
POST_MORTEM → [CLOSED]

Key Rules for P1/P2: - Post-mortem is mandatory for P1/P2 incidents in PRD environment - Cannot skip POST_MORTEM status - must go through it before closing - From MITIGATING: Can only go to MITIGATED, not to POST_MORTEM or CLOSED - From MITIGATED: Can only go to POST_MORTEM, not directly to CLOSED - Closure with reason: Only allowed from OPEN and INVESTIGATING statuses

P3/P4/P5 Incidents (Priority 3+ or Non-PRD)¤

OPEN → [INVESTIGATING, CLOSED (with reason)]
INVESTIGATING → [MITIGATING, CLOSED (with reason)]
MITIGATING → [MITIGATED]
MITIGATED → [CLOSED]

Key Rules for P3+: - No post-mortem required - POST_MORTEM status is not available - Direct closure: Can close directly from MITIGATED without intermediate steps - Closure with reason: Only allowed from OPEN and INVESTIGATING statuses

Closure Reason Requirements¤

A closure reason form is required when closing an incident directly from: - OPEN status - INVESTIGATING status

This applies to all priority levels (P1-P5).

Implementation Details¤

Status Values¤

  • OPEN = 10
  • INVESTIGATING = 20
  • MITIGATING = 30 (labeled as "Mitigating")
  • MITIGATED = 40 (labeled as "Mitigated")
  • POST_MORTEM = 50
  • CLOSED = 60

Form Logic Location¤

The workflow logic is implemented in: - Form: src/firefighter/incidents/forms/update_status.py - Enum: src/firefighter/incidents/enums.py - Tests: tests/test_incidents/test_forms/test_workflow_transitions.py

Priority Detection¤

P1/P2 incidents requiring post-mortem are detected by: 

requires_postmortem = (
    incident.priority
    and incident.environment
    and incident.priority.needs_postmortem
    and incident.environment.value == "PRD"
)

Testing¤

Comprehensive workflow tests are located in: - tests/test_incidents/test_forms/test_workflow_transitions.py - Complete workflow validation - tests/test_incidents/test_forms/test_update_status_workflow.py - Legacy tests (some skipped) - tests/test_slack/views/modals/test_update_status.py - Slack integration tests

Migration Notes¤

This workflow was implemented to replace a previous more permissive workflow that allowed invalid transitions. The new implementation:

  1. Restricts transitions to exactly match the business workflow requirements
  2. Enforces post-mortem completion for P1/P2 incidents in PRD
  3. Simplifies P3+ workflow by removing unnecessary post-mortem steps
  4. Validates closure reasons for early-stage closures
  • Forms: src/firefighter/incidents/forms/update_status.py
  • Enums: src/firefighter/incidents/enums.py
  • Slack Integration: src/firefighter/slack/views/modals/update_status.py
  • Utilities: src/firefighter/slack/views/modals/utils.py
  • Tests: tests/test_incidents/test_forms/test_workflow_transitions.py