Skip to main content

Problem State Protocols

Understanding the Core Components​

To grasp problem state protocols, it's essential to understand four fundamental concepts: Problems, Status, States, and Interventions.

What is a Problem?​

A Problem represents a specific health concern or condition that requires clinical attention. For example:

  • Depression Symptoms
  • Eye Health Concerns
  • Diabetes Management
  • Anxiety Disorders
  • Housing
  • Food Insecurity
  • Financial Insecurity

Each problem follows a structured lifecycle. Many are managed through our protocol system, while others may still use manual or legacy processes as protocols are gradually rolled out.

Problem Status (Goal-Level Tracking)​

Problem Status tracks the high-level progress toward resolving the entire problem:

enum ProblemGoalStatus {
  NEW = 'new', // Problem has been identified
  IN_PROGRESS = 'in_progress', // Problem is actively being addressed
  COMPLETED = 'completed', // Problem has been successfully resolved
  HOLD = 'hold', // Problem is temporarily paused and not currently being addressed
  CANCELLED = 'cancelled', // Problem has been discontinued or withdrawn
}

Status Flow Example:

const problemGoalStatusFlow = {
  'new' → 'in_progress',
  'in_progress' → 'completed',
  'in_progress' → 'hold',
  'in_progress' → 'cancelled',
  'hold' → 'in_progress'
};

Problem State (Granular Clinical Tracking)​

Problem State provides detailed, condition-specific progression tracking. Unlike status transitions, state transitions are not necessarily linear—some problems follow a straightforward, step-by-step progression, while others allow movement in multiple directions based on patient progress, setbacks, or changing clinical conditions.

⚠️ Disclaimer: The following examples illustrate possible problem states and transitions for clarity. Actual state names and transitions may differ from those implemented in the codebase.

Depression Example
  • Possible states: assess, at_risk, moderate, severe, severe_si_risk, remission_recent, remission_maintained
  • Non-linear transitions: A patient can move from at_risk → severe (worsening), severe → remission_recent (improvement), or remission_recent → moderate (relapse). Special escalation to severe_si_risk can occur from any state when suicide risk is identified.
  • Severity levels:
    • severe and severe_si_risk are marked as acute severity
    • remission_maintained is marked as stable severity
  • Key triggers:
    • PHQ-9 scores determine most transitions
    • Suicide risk assessment immediately escalates to severe_si_risk
    • Two consecutive PHQ-9 scores under 10 transition from remission_recent to remission_maintained
  • View protocol source code
Eye Health Example
Diabetes Example
  • Possible states: Assess, Controlled, Uncontrolled, Stable
  • Patients can cycle between: Controlled ↔ Uncontrolled
  • View protocol source code

Note: The protocol system evaluates current patient data and current state to determine the appropriate state transition.

Interventions: The Clinical Actions​

Interventions are specific, actionable steps performed by care team members—including Lead Care Managers (LCMs), Registered Nurses (RNs), Nurse Practitioners (NPs), and others—to address problems:

➡️ Learn more about Interventions

Depression Interventions:​

  • Complete Forms: PHQ9
  • Coordinate Pair Team Appointment

Eye Health Interventions:​

  • Coordinate Eye Care Appointment

Problem State Protocols: Automation & Intelligence​

Protocols are decision-support systems that automate many state transitions, but also support manual transitions when needed. For some protocols, manual transitions are required to ensure clinical judgment and flexibility in patient care.

  1. Analyze the current problem state
  2. Determine appropriate interventions
  3. Automatically trigger necessary actions
  4. Guide LCMs through evidence-based care paths

Note: The in_progress status is broad and covers many different steps. Inside in_progress, we use more detailed problem states to track exactly what is happening with the patient. This gives us a clearer and more accurate picture of their progress.

By implementing problem state protocols, LCMs can focus on patient care rather than administrative decision-making, while ensuring consistent, high-quality treatment approaches across all patients and conditions.

Technical Implementation​

We are implementing problem state protocols to define how each problem should behave throughout its lifecycle. These protocols determine:

  • The set of possible states for a problem
  • Which interventions are linked to each state
  • How transitions between states occur

🔧 Main Components​

📄 Protocol Definition Schema​

Defines the structure of a protocol, including its states and transitions.
➡️ Read more

🧠 Protocol Definition​

Responsible for evaluating a problem goal's state by iterating through transition rules.
➡️ View code

Key behavior:

  • Calls the fetcher to get the current values and applies the operator and value defined in the protocol.
  • If any rule evaluates truthfuly, it will return the new state in the response object.
  • The order of the transitions is important, since they will be evaluated from top to bottom, and will return the state of the first one that evaluates to true.
  • Returns a EvaluationResults::EvaluationResult.

⚙️ Problem State Processor​

Evaluates and updates the problem's state using the protocol definition.
Also handles creation of interventions and other side effects.
➡️ Read more

🔍 Data Fetcher​

Fetches data from ARC used in state evaluations to decide if it should transition states.
➡️ Read more

🛡️ Guardian​

Determines if a problem should be evaluated.
➡️ View code

Conditions:

  • :problem_states feature flag is enabled
  • The problem goal already has a protocol associated (if it was already evaluated, it will keep being evaluated even if patient in not enabled pod or problem no longer supported)
  • Patient is in an enabled care pod for the problem: (APP_CONFIG.ProblemStates.ProtocolRolloutConfig)

🧪 Frontend Feature Flag​

The UI uses its own feature flag: :problem_states_ui, enabled per user email.

📊 Collector (Instrumentation)​

Responsible for observability over the protocol executions.
➡️ View code

Tracked data includes:

  • Trigger source
  • Manual transitions
  • Evaluation results
  • Intervention created
  • Intervention updated
  • Transition and condition evaluation
  • Callback executions

🧭 Userflow​

We use Userflow to help care team members understand the current state and next steps.

  • Tooltips are placed using CSS selectors and element IDs
  • All relevant element ids should use the userflow- prefix
  • If a flow needs to target a new element, add the corresponding ID

📍 Added id example

🛠️ Creating or Updating a Protocol​

Complete guide for setting up new protocols or updating existing ones.
➡️ Read more