> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Treatment Plans

> Dashboard listing treatment plans due for review within a configurable time window (30, 60, or 90 days), with overdue indicators.

The Treatment Plans screen at `/cl/treatment-plans` shows all treatment plans whose review is due within a selected time window and provides entry points for creating a new plan.

## Overview

The page renders a header with a "New Plan" button (permission-gated to `cl.treatment_plan.create`) and three filter tabs: 30 Days, 60 Days, and 90 Days. The `useTreatmentPlanList` hook fetches plans whose `review_due_date` falls within the selected window. Each plan row is a link to `/cl/treatment-plans/:planId` and shows: plan type (formatted from `plan_type`), chart number, service line, an overdue badge (destructive) when `review_due_date` is in the past, a relative due-date string otherwise, and a status badge (`draft` / `active` / `signed`). Clicking "New Plan" opens a `TemplateSelectStep` dialog; the user may select a template (navigates to `/cl/treatment-plans/new` with `state.templateId`) or choose a blank plan (navigates to `/cl/treatment-plans/new`).

## Who it's for

Requires permission: `cl.treatment_plan.view`

Creating a new plan additionally requires: `cl.treatment_plan.create`

## Before you start

* Must hold `cl.treatment_plan.view`.
* Treatment plans are associated with patient charts via `cl_patient_charts`.

## Steps

<Steps>
  <Step title="Select the review window">Use the tab bar to choose 30, 60, or 90 days. The list refreshes to show plans due within that window.</Step>
  <Step title="Identify overdue plans">Plans with a `review_due_date` in the past show a red "Overdue" badge. Plans with a future due date show a relative time string (e.g., "due in 5 days").</Step>
  <Step title="Open a plan">Click any row to navigate to the Treatment Plan detail at `/cl/treatment-plans/:planId`.</Step>
  <Step title="Create a new plan (if permitted)">Click "New Plan" to open the template-selection dialog. Choose a template or a blank plan. Both paths navigate to `/cl/treatment-plans/new`.</Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Review window filter">
    The filter tabs control the `daysFilter` state (30, 60, or 90). `useTreatmentPlanList` receives this value and returns plans due within that many days.
  </Accordion>

  <Accordion title="Plan status badges">
    Statuses observed in code: `draft` (outline badge), `active` (secondary badge), `signed` (default badge). Any unrecognized status falls back to outline.
  </Accordion>

  <Accordion title="Template selection">
    The `TemplateSelectStep` dialog offers a template picker or a blank-plan option. Selecting a template passes `state.templateId` in navigation state to the new-plan route.
  </Accordion>

  <Accordion title="Error and empty states">
    Load error: destructive card with sanitized message above the list. Empty list: "No plans due — No treatment plans due for review within N days."
  </Accordion>
</AccordionGroup>

## Detail view

The Treatment Plan screen at `/cl/treatment-plans/:planId` displays the full detail of a single treatment plan, including goals, interventions, signatures, caregiver participation, and goal-progress visualizations.

### Overview

The page loads a plan by `planId` via `useTreatmentPlanDetail` and also loads the associated chart via `useChartDetail`. The header shows plan type (formatted from `plan_type`), service line, effective date, review due date, and status badge. The plan is editable when `status` is `draft` or `active`. A `GoalProgressCharts` component renders goal-progress visualization. A `CaregiverParticipationSection` shows caregiver role and participation timestamp. A Patient Signature card shows whether the patient has signed (and if they agreed or disagreed, showing "appeal rights provided" on disagreement). The Goals card lists goals as collapsible rows showing `goal_text_patient_words`, `measurable_criteria`, frequency, duration, target date, `progress_pct`, and status badge; each goal expands to show its interventions (description, frequency, modality). A `CODTreatmentPlanSection` appears based on the chart's `cod_indicator`. `TreatmentPlanSignatures` renders the signature section at the bottom.

### Who it's for

Requires permission: `cl.treatment_plan.view`

Additional actions require: `cl.treatment_plan.create` (Add Goal, Add Intervention), `cl.treatment_plan.patient_sign` (Record Patient Signature), `cl.treatment_plan.event_automation` (Record Life Event).

### Before you start

* Must hold `cl.treatment_plan.view`.
* Navigate here from the Treatment Plans list at `/cl/treatment-plans` or from the Treatment Plans tab on a Patient Chart.

### Steps

<Steps>
  <Step title="Open a treatment plan">Navigate to `/cl/treatment-plans` and click a plan row, or click a plan from the Treatment Plans tab on a Patient Chart. The plan header loads with type, service line, dates, and status badge.</Step>
  <Step title="Review plan header and progress">Read the plan header (type, service line, effective date, review due date, status). The `GoalProgressCharts` component shows progress visualization for all goals.</Step>
  <Step title="Review caregiver participation">The `CaregiverParticipationSection` shows caregiver role and the timestamp of recorded participation when applicable.</Step>
  <Step title="Review patient signature status">The Patient Signature card shows "Signed (agrees)", "Signed (disagrees — appeal rights provided)", or "Not yet signed". If unsigned and the plan is editable, the "Record Patient Signature" button is shown to users with `cl.treatment_plan.patient_sign`.</Step>
  <Step title="Expand goals to see interventions">Click any goal row to expand it and view its linked interventions (description, frequency, modality). Add new goals (if editable and permitted) via the "Add Goal" button in the Goals card header.</Step>
  <Step title="Record a life event (if permitted)">Users with `cl.treatment_plan.event_automation` can click "Record Life Event" to open `LifeEventRecordForm`.</Step>
  <Step title="Review signatures">The `TreatmentPlanSignatures` section at the bottom shows signature records for the plan.</Step>
</Steps>

### Key concepts

<AccordionGroup>
  <Accordion title="Plan editability">
    The plan is editable (`isEditable = true`) only when `status` is `draft` or `active`. When `signed`, `superseded`, or `discontinued`, goal and intervention Add buttons are hidden and patient-signature capture is disabled.
  </Accordion>

  <Accordion title="Goal status values">
    Goal statuses in code: `not_started` (outline), `in_progress` (secondary), `partially_met` (secondary), `met` (default), `revised` (outline), `discontinued` (destructive). Goals display `goal_text_patient_words` as the primary text and `measurable_criteria` as secondary.
  </Accordion>

  <Accordion title="COD Treatment Plan Section">
    When the associated chart's `cod_indicator` is truthy, a `CODTreatmentPlanSection` is rendered between the goals and the signatures. SME: confirm COD documentation requirements.
  </Accordion>

  <Accordion title="Error and empty states">
    Load error: destructive card with sanitized message. Plan not found: "Treatment plan not found" empty-state card. No goals yet: "No goals added yet." No interventions: "No interventions yet."
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/cl.tsx
  * src/cores/cl/pages/TreatmentPlanListPage.tsx
  * src/cores/cl/pages/TreatmentPlanDetailPage.tsx
  * src/cores/cl/hooks/useChartDetail.ts
</Accordion>