> ## 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.

# Discharge Plans

> List, search, view, and create resident discharge plans with checklist, referral, and follow-up management.

The Discharge Plans page lists all discharge plans for the current organization with search and status filtering, accessible at `/rh/discharge-plans`.

## Overview

The page uses `useDischargePlans` to load all discharge plans for the current organization. Soft-deleted plans (`deleted_at` set) are excluded from display. Users can filter by free-text search (partial match on `episode_id` or `notes`) and by status (`all`, `not_started`, `in_progress`, `completed`). Clicking a row navigates to `/rh/discharge-plans/{id}`.

## Who it's for

No additional permission gate is present on `/rh/discharge-plans` beyond the outer `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`) guard.

Note: Creating a new discharge plan via `/rh/discharge-plans/new` requires `RH_PERMISSIONS.RESIDENTS_DISCHARGE` (`rh.residents.discharge`).

## Before you start

* Your account must hold `rh.dashboard.view`.
* An organization context must be active; plans are scoped by `organization_id` inside `useDischargePlans`.

## Steps

<Steps>
  <Step title="Open Discharge Plans">
    Navigate to **Recovery Housing → Discharge Plans** or go directly to `/rh/discharge-plans`. The list loads with all non-deleted plans for your organization.
  </Step>

  <Step title="Search plans">
    Type in the search box to filter plans by a partial match on `episode_id` or `notes`. The filter runs client-side on the already-loaded dataset.
  </Step>

  <Step title="Filter by status">
    Use the **Filter by status** dropdown to narrow the list to `not_started`, `in_progress`, or `completed` plans.
  </Step>

  <Step title="Open a plan">
    Click any row in the `DischargePlansTable` to navigate to that plan's detail page at `/rh/discharge-plans/{id}`.
  </Step>
</Steps>

## Key concepts

| Status      | Value         | Notes                                           |
| ----------- | ------------- | ----------------------------------------------- |
| Not Started | `not_started` | Plan exists but discharge process has not begun |
| In Progress | `in_progress` | Discharge process is underway                   |
| Completed   | `completed`   | Discharge has been finalized                    |

| Field        | Search behavior                                 |
| ------------ | ----------------------------------------------- |
| `episode_id` | Partial lowercase match                         |
| `notes`      | Partial lowercase match                         |
| `deleted_at` | Plans with a non-null value are always excluded |

## Viewing a discharge plan

The Discharge Plan Details page shows the full record for a single discharge plan and its associated checklist, referrals, and follow-ups, accessible at `/rh/discharge-plans/:id`.

The page loads a discharge plan by `id` via `useDischargePlan` and its checklists via `useDischargeChecklists`. A details card shows plan metadata (expected/actual discharge dates, discharge type, destination, readiness score, housing/employment/continuing-care planned flags, and notes). Three tabs — **Checklist**, **Referrals**, and **Follow-Ups** — provide sub-section management. Action buttons allow editing the plan and, if not yet completed, completing the discharge.

No additional permission gate is present beyond `rh.dashboard.view`. A valid discharge plan `id` must exist; the page displays "Plan not found" if the query returns no result.

<Steps>
  <Step title="Open a discharge plan">
    Navigate from the Discharge Plans list (`/rh/discharge-plans`) and click a row, or go directly to `/rh/discharge-plans/{id}`. A skeleton displays while the plan loads.
  </Step>

  <Step title="Review plan details">
    The **Plan Details** card shows expected discharge date, actual discharge date (if set), discharge type, destination, readiness score (checklist completion %), housing placement planned, employment referral planned, continuing care planned, and notes.
  </Step>

  <Step title="Manage the checklist">
    On the **Checklist** tab, view incomplete vs. complete checklist items. Click **Add Item** (surfaces via `DischargeChecklistCard`) to open `DischargeChecklistDialog` and add a new item. The readiness score updates with checklist completion.
  </Step>

  <Step title="Manage referrals">
    On the **Referrals** tab, view existing referrals. Click **Add Referral** to open `ReferralDialog`. Click a referral row to navigate to `/rh/referrals/{id}`.
  </Step>

  <Step title="Manage follow-ups">
    On the **Follow-Ups** tab, view scheduled follow-up contacts. Click **Schedule Follow-Up** to open `FollowUpScheduleDialog`. Click **Log Contact** on a scheduled follow-up to open `FollowUpContactDialog`.
  </Step>

  <Step title="Edit the plan">
    Click **Edit Plan** (top-right) to open `DischargePlanDialog` pre-populated with current plan values. Save to update.
  </Step>

  <Step title="Complete the discharge">
    If `plan.status` is not `completed`, click **Complete Discharge** to open `CompleteDischargeDialog`. The dialog is passed the count of incomplete checklist tasks. On success, the page navigates to `/rh/discharge-plans`.
  </Step>
</Steps>

### Key concepts

| Field                     | Source                                    | Notes                                                                     |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
| `readiness_score`         | Computed: `completed / total * 100`       | 0 if no checklist items; code-derived, not clinically validated           |
| `expected_discharge_date` | `plan.expected_discharge_date`            | Formatted `MMM d, yyyy`                                                   |
| `actual_discharge_date`   | `plan.actual_discharge_date`              | Displayed as "Not discharged" if null                                     |
| `discharge_type`          | `custom_fields.discharge_type`            | Value from `custom_fields`; displayed with underscores replaced by spaces |
| `discharge_destination`   | `custom_fields.discharge_destination`     | Same format as above                                                      |
| `status`                  | `plan.status`                             | Controls visibility of "Complete Discharge" button                        |
| `incompleteChecklist`     | `checklists.filter(!is_completed).length` | Passed to `CompleteDischargeDialog`                                       |

## Creating a discharge plan

The New Discharge Plan wizard guides users through creating a discharge plan for a resident episode, accessible at `/rh/discharge-plans/new`.

The wizard uses a four-step timeline layout (`WizardShell` with `layout="timeline"`). A `?episodeId=<uuid>` query parameter is required — if missing, the page renders a message stating "An episode ID is required to create a discharge plan. Navigate here from an episode detail page" and the wizard does not render. After clicking **Finalize discharge plan**, the wizard calls `createDischargePlan` and navigates to the new plan's detail page. Exiting at any step navigates to `/rh/discharge-plans` without saving.

This route requires `RH_PERMISSIONS.RESIDENTS_DISCHARGE` (`rh.residents.discharge`) in addition to `rh.dashboard.view`.

Before you start: hold both `rh.dashboard.view` and `rh.residents.discharge`. Navigate from a resident episode detail page to ensure the required `episodeId` query parameter is passed; direct navigation without this parameter will display a blocking message instead of the wizard.

<Steps>
  <Step title="Step 1 — Discharge Type">
    Select the **Discharge Type** (Planned, Voluntary, Administrative, Clinical, or Transfer), set the **Planned Discharge Date**, and enter the **Reason for Discharge**. An optional **Additional Notes** field is available. All three primary fields are required; validation runs on **Next**.
  </Step>

  <Step title="Step 2 — Checklists & Referrals">
    Review and check off the default **Discharge Checklist** items (benefits transition, housing placement, transportation, medications reconciled, aftercare program, emergency contact). Add one or more **Referrals** by selecting a category (e.g., Outpatient treatment, Employment services, Medical care), entering a provider name, and optionally setting a scheduled date. This step has no required-field validation gate; proceed with **Next** at any checklist state.
  </Step>

  <Step title="Step 3 — Housing & Follow-Up">
    Select the **Housing Destination Type** (own home, family home, sober living, shelter, unknown, or other). If the destination is not `unknown`, an optional address field appears. Toggle the **7-day**, **30-day**, and **90-day** follow-up checkboxes (all default to on). Optionally enter a **Follow-up Contact Name** and **Phone**. Housing type is required; validation runs on **Next**.
  </Step>

  <Step title="Step 4 — Review & Finalize">
    Review a summary of all collected data on the `DischargePlanReviewStep` screen. Click **Finalize discharge plan** to submit. On success a toast confirms the plan was finalized and the page navigates to the new discharge plan detail. On error a sanitized error message appears in a toast.
  </Step>
</Steps>

### Key concepts

| Term                       | Code identifier                          | Notes                                         |
| -------------------------- | ---------------------------------------- | --------------------------------------------- |
| Discharge Type             | `DischargeTypeStep`                      | Type, planned date, reason, notes             |
| Checklists & Referrals     | `ChecklistsReferralsStep`                | Checklist toggles and referral entries        |
| Housing & Follow-Up        | `HousingFollowUpStep`                    | Destination type, address, follow-up schedule |
| Review & Finalize          | `DischargePlanReviewStep`                | Read-only summary before submission           |
| `discharge_type`           | `custom_fields.discharge_type`           | Stored in `custom_fields` on the plan record  |
| `housing_destination_type` | `custom_fields.housing_destination_type` | Post-discharge housing category               |
| Follow-up flags            | `custom_fields.follow_up_7_day` etc.     | Boolean flags stored in `custom_fields`       |

## Related

<Columns cols={2}>
  <Card title="Recovery Housing" icon="house" href="/rh/references">
    Recovery Housing references and overview.
  </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/rh.tsx
  * src/cores/rh/pages/discharge/DischargePlanningPage.tsx
  * src/cores/rh/pages/discharge/DischargePlanDetailPage.tsx
  * src/cores/rh/pages/DischargePlanningWizardPage.tsx
  * src/cores/rh/hooks/discharge/useDischargePlans.ts
  * src/cores/rh/hooks/discharge/useDischargePlan.ts
  * src/cores/rh/hooks/discharge/useDischargeChecklists.ts
  * src/cores/rh/components/wizards/discharge-planning-wizard/DischargePlanningWizard.tsx
  * src/cores/rh/components/wizards/discharge-planning-wizard/steps/DischargeTypeStep.tsx
  * src/cores/rh/components/wizards/discharge-planning-wizard/steps/ChecklistsReferralsStep.tsx
  * src/cores/rh/components/wizards/discharge-planning-wizard/steps/HousingFollowUpStep.tsx
</Accordion>