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

# Recovery Housing Assessments

> List, filter, view, create, and manage post-discharge outcome assessments and record outcome measurements and checkpoints.

The Assessments screen at `/rh/outcomes/assessments` lists all outcome assessments for the current organization, allows filtering by status and type, and provides entry points to create new assessments, manage outcome checkpoints, and record individual measurements.

## Overview

The page loads assessments via `useOutcomeAssessments` filtered by `organization_id`. Active checkpoints are loaded in parallel via `useOutcomeCheckpoints` with `isActive: true`. The filter bar provides a text search (matching against `notes` and assessment `id`) plus status and type dropdowns. Status options are `pending`, `in_progress`, `completed`, and `missed`. Type options are `baseline` and `follow_up`. Below the Assessments card, an **Outcome Measurements** card shows active checkpoint badges from `useOutcomeCheckpoints`, a **Manage Checkpoints** button, a **Record Measurement** button, and an `OutcomeMeasurementsTable`. The **New Assessment** button in the header opens an `OutcomeAssessmentDialog`. The **New Assessment (wizard)** route at `/rh/outcomes/assessments/new` is gated by `RH_PERMISSIONS.OUTCOMES_ASSESSMENTS_CREATE`.

## Who it's for

No route-level `RequirePermission` on `/rh/outcomes/assessments` beyond the outer `RHViewGuard` (`rh.dashboard.view`). The wizard route `/rh/outcomes/assessments/new` requires `RH_PERMISSIONS.OUTCOMES_ASSESSMENTS_CREATE` (`rh.outcomes.assessments.create`).

## Before you start

* Hold `rh.dashboard.view` to access the RH module.
* Hold `rh.outcomes.assessments.create` to use the new-assessment wizard route.

## Steps

<Steps>
  <Step title="Open the Assessments list">
    Navigate to `/rh/outcomes/assessments`. The Assessments card shows a count of records matching current filters.
  </Step>

  <Step title="Filter assessments">
    Enter text in the search field to match against `notes` or assessment ID. Use the Status dropdown to filter by `pending`, `in_progress`, `completed`, or `missed`. Use the Type dropdown to filter by `baseline` or `follow_up`.
  </Step>

  <Step title="Create a new assessment">
    Click **New Assessment** in the page header. The `OutcomeAssessmentDialog` opens inline. To use the full wizard, navigate to `/rh/outcomes/assessments/new` (requires `rh.outcomes.assessments.create`).
  </Step>

  <Step title="Manage checkpoints">
    In the Outcome Measurements card, click **Manage Checkpoints** to open the `OutcomeCheckpointDialog`.
  </Step>

  <Step title="Record a measurement">
    Click **Record Measurement** in the Outcome Measurements card to open the `OutcomeMeasurementDialog`.
  </Step>

  <Step title="Open an assessment record">
    Click a row in the Assessments table to navigate to `/rh/outcomes/assessments/:id`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Empty state">
    When no assessments match current filters, the card shows "No assessments found" with a **Create First Assessment** button.
  </Accordion>

  <Accordion title="Loading state">
    While `useOutcomeAssessments` is fetching, five skeleton rows are shown in the assessments card. Checkpoint badges in the measurements card also show skeleton placeholders.
  </Accordion>

  <Accordion title="Active checkpoints">
    The badge strip in the Outcome Measurements card shows all checkpoints where `is_active` is `true`. When none exist, "No active checkpoints configured yet." is displayed.
  </Accordion>
</AccordionGroup>

## Viewing an assessment

The Assessment Details screen at `/rh/outcomes/assessments/:id` displays the full record for one outcome assessment, showing the checkpoint name, assessment type and status, dates, completed-by staff name, notes, linked episode, and individual outcome measurements.

The page reads `:id` from URL params and loads the assessment via `useOutcomeAssessmentDetail`. The breadcrumb is set to the checkpoint name (`assessment.checkpoint?.checkpoint_name`) or "Assessment" as fallback. The header shows an `OutcomeAssessmentStatusBadge` and an `AssessmentTypeBadge`. An **Edit** button is shown when status is not `completed`; a **Complete Assessment** button appears when status is `in_progress` (currently a no-op — see SME note). The **Assessment Details** card surfaces: Checkpoint, `days_post_discharge`, Assessment Type, Assessment Date, Completed Date, Completed By staff name, and Status. Notes render when present. The **Episode** sidebar card shows the Episode ID (first 8 characters) with a **View Episode** link to `/rh/episodes/:id`. The **Outcome Measurements** card renders `OutcomeMeasurementsTable` filtered by `episode_id`. An **Add Measurement** button appears when status is not `completed`. If the record is missing or errored, "Assessment not found or an error occurred." is displayed.

No route-level `RequirePermission` beyond the outer `RHViewGuard` (`rh.dashboard.view`). The assessment record must exist; a non-existent `:id` shows an error card.

<Steps>
  <Step title="Open an assessment record">
    From `/rh/outcomes/assessments`, click a row to navigate to `/rh/outcomes/assessments/:id`.
  </Step>

  <Step title="Review assessment details">
    The **Assessment Details** card shows checkpoint name, days post-discharge, type, dates, who completed it, and current status.
  </Step>

  <Step title="Review notes">
    If `assessment.notes` is present, it renders below the detail grid.
  </Step>

  <Step title="Navigate to the linked episode">
    The **Episode** sidebar card shows the first 8 characters of the episode ID. Click **View Episode** to open `/rh/episodes/:id`.
  </Step>

  <Step title="Record a measurement (when status is not completed)">
    In the **Outcome Measurements** card, click **Add Measurement** to record a new outcome measurement for this assessment.
  </Step>

  <Step title="Edit the assessment (when status is not completed)">
    Click **Edit** to navigate to `/rh/outcomes/assessments/:id/edit`.
  </Step>

  <Step title="Complete the assessment (when status is in_progress)">
    Click **Complete Assessment**. This action is currently a placeholder — see SME note above.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Error / not-found state">
    If `useOutcomeAssessmentDetail` returns an error or no data, the page shows "Assessment not found or an error occurred."
  </Accordion>

  <Accordion title="Loading state">
    While data is fetching, two skeleton rows replace the header and content area.
  </Accordion>

  <Accordion title="Status-gated actions">
    Edit and Add Measurement buttons are hidden when `assessment.status === 'completed'`. The Complete Assessment button only appears when `assessment.status === 'in_progress'`.
  </Accordion>
</AccordionGroup>

## Creating an assessment

The New Assessment wizard guides users through completing a resident outcome assessment, accessible at `/rh/outcomes/assessments/new`.

The wizard uses a three-step timeline layout (`WizardShell` with `layout="timeline"`). An optional `?episodeId=<uuid>` query parameter pre-populates the episode context. An episode ID is enforced at submission time — the form renders but cannot be submitted without one. After clicking **Submit assessment**, the wizard calls `createAssessment` and navigates to the new assessment detail page. Exiting at any step navigates to `/rh/outcomes/assessments` without saving.

This route requires `RH_PERMISSIONS.OUTCOMES_ASSESSMENTS_CREATE` (`rh.outcomes.assessments.create`) in addition to the outer `rh.dashboard.view` guard.

Before you start: hold both `rh.dashboard.view` and `rh.outcomes.assessments.create`. An organization context must be active. Navigate from an episode detail page or the Outcome Assessments list to pass the required `episodeId` query parameter; directly navigating to the URL without an episode ID will allow wizard entry but will block final submission.

<Steps>
  <Step title="Step 1 — Assessment Context">
    Select the **Assessment Type** (Baseline or Follow-Up) and set the **Assessment Date** and **Assessment Period**. Available periods are: Intake, 30-Day, 60-Day, 90-Day, Discharge, 6-Month Follow-Up, 12-Month Follow-Up. All three fields are required; a validation toast appears if any are missing on **Next**.
  </Step>

  <Step title="Step 2 — Instrument Sections">
    Complete responses across four sections: **Substance Use**, **Housing Stability**, **Employment & Education**, and **Well-Being**. Each section is navigated with tab buttons; a completion percentage is shown per section. No section is enforced as required at this step, but all fields accept free-text or numeric input.
  </Step>

  <Step title="Step 3 — Review & Submit">
    Review a summary of the context and instrument responses on the `AssessmentReviewSubmitStep` screen. Click **Submit assessment** to finalize. On success a toast confirms submission and the page navigates to the new assessment detail page. On error a sanitized error message appears in a toast.
  </Step>
</Steps>

### Key concepts

| Term                   | Code identifier                      | Notes                                                |
| ---------------------- | ------------------------------------ | ---------------------------------------------------- |
| Assessment Context     | `AssessmentContextStep`              | Type, date, period                                   |
| Instrument Sections    | `InstrumentSectionsStep`             | Four sections with per-section questions             |
| Review & Submit        | `AssessmentReviewSubmitStep`         | Read-only summary before final submission            |
| `assessment_type`      | `context.assessment_type`            | `baseline` or `follow_up`                            |
| `assessment_period`    | `custom_fields.assessment_period`    | Stored in `custom_fields`                            |
| `instrument_responses` | `custom_fields.instrument_responses` | Array of section responses 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/OutcomeAssessmentsPage.tsx
  * src/cores/rh/pages/OutcomeAssessmentDetailPage.tsx
  * src/cores/rh/pages/OutcomesAssessmentWizardPage.tsx
  * src/cores/rh/hooks/useOutcomeAssessments.ts
  * src/cores/rh/components/wizards/outcomes-assessment/OutcomesAssessmentWizard.tsx
  * src/cores/rh/components/wizards/outcomes-assessment/steps/AssessmentContextStep.tsx
  * src/cores/rh/components/wizards/outcomes-assessment/steps/InstrumentSectionsStep.tsx
</Accordion>