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

# LoC Assessments

> List and filter Level-of-Care assessments (ASAM and LOCUS instruments); create new assessments with prior-assessment delta and dimensional scoring.

This screen lists Level-of-Care (LoC) assessments for the current organization and is available at `/cl/loc-assessments`.

## Overview

The LoC Assessments list page renders all records from `cl_loc_assessments` scoped to the current organization, using the `LocAssessmentListTable` component. Records are filtered to non-deleted rows and ordered by `assessed_at` descending. An instrument filter dropdown allows narrowing the list to `ASAM` or `LOCUS` assessments, or showing all instruments. Users see a **New Assessment** button that navigates to `/cl/loc-assessments/new`. Clicking a row in the table navigates to the detail page at `/cl/loc-assessments/:assessmentId`. The signing flow requires a `final_loc_code`; when this differs from `recommended_loc_code`, an `override_reason_code` and a rationale of at least 20 characters are required (enforced client-side and by a DB trigger).

## Who it's for

Requires permission: `cl.loc_assessment.view`

Creating new assessments additionally requires: `cl.loc_assessment.create`

## Before you start

You must hold `cl.loc_assessment.view` to access this page. Assessments are scoped to your current organization.

## Steps

<Steps>
  <Step title="Open LoC Assessments">
    Navigate to `/cl/loc-assessments`. All non-deleted assessments for your organization load, ordered most recent first.
  </Step>

  <Step title="Filter by instrument (optional)">
    Use the instrument dropdown (All Instruments / ASAM / LOCUS) to narrow the list.
  </Step>

  <Step title="Review the assessments table">
    The table is rendered by `LocAssessmentListTable`. Click any row to open the detail page at `/cl/loc-assessments/:assessmentId`.
  </Step>

  <Step title="Create a new assessment (if permitted)">
    Click **New Assessment** (requires `cl.loc_assessment.create`) to navigate to `/cl/loc-assessments/new`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Instrument filter values">
    The dropdown maps to `instrument_type` column values: `asam` and `locus`. Selecting "All Instruments" removes the filter.
  </Accordion>

  <Accordion title="Assessment statuses">
    The `status` field progresses to `signed` upon finalization. The signing mutation sets `signed_at` and `signed_by`. An override (where `final_loc_code !== recommended_loc_code`) requires a reason code and rationale.
  </Accordion>

  <Accordion title="Loading state">
    The list table component (`LocAssessmentListTable`) receives an `isLoading` prop and handles the skeleton/loading state internally.
  </Accordion>
</AccordionGroup>

## Creating a LoC assessment

The New LoC Assessment page at `/cl/loc-assessments/new` allows a clinician to create a new level-of-care assessment. Requires `cl.loc_assessment.create`.

The page accepts optional `patientId` and `priorId` URL search params for pre-population. The user selects an instrument type (`asam` or `locus`) and enters (or confirms) a patient ID. When a prior assessment ID is supplied via `priorId`, a `LocTransitionRecommendationCard` and a `LocReassessmentDeltaTable` are displayed above the form, showing the prior recommended LoC code, the current preview recommendation, and a dimensional delta table. The `LocAssessmentForm` component captures dimensional scores and emits a `recommended_loc_code` on change. On save, `useCreateLocAssessment` creates the record in `cl_loc_assessments` with `status: 'draft'` and navigates to the detail page at `/cl/loc-assessments/:id`. The new record links to the prior assessment via `supersedes_id` when reassessing.

**Before you start:** have the patient's chart ID available (the page accepts a `patientId` query param, or you can type it into the Patient ID field). To reassess from a prior assessment, include a `priorId` query param with the prior assessment's ID.

<Steps>
  <Step title="Navigate to New LoC Assessment">
    Go to `/cl/loc-assessments/new`. Optional: append `?patientId=<id>` and/or `?priorId=<priorAssessmentId>` to pre-populate the form.
  </Step>

  <Step title="Enter the patient ID">
    Type the patient chart ID in the Patient ID field, or confirm the pre-populated value from the URL param.
  </Step>

  <Step title="Select the instrument type">
    Choose "ASAM Criteria (Substance Use)" or "LOCUS (Mental Health)" from the Instrument dropdown. The default is `asam`.
  </Step>

  <Step title="Review prior assessment delta (reassessment only)">
    If a prior assessment was loaded via `priorId`, the LocTransitionRecommendationCard shows the prior final LoC code vs. the current preview recommendation. The LocReassessmentDeltaTable shows per-dimension score changes.
  </Step>

  <Step title="Complete dimensional scoring">
    Fill in the dimensional scores in the LocAssessmentForm. The form emits a `recommended_loc_code` preview as scores change.
  </Step>

  <Step title="Save the assessment">
    Click Save in the LocAssessmentForm. The assessment is created with `status: 'draft'` and you are redirected to the detail page at `/cl/loc-assessments/:id` to review and sign.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Instrument types">
    The `instrument_type` field accepts `asam` or `locus`. Labels rendered in the UI are "ASAM Criteria (Substance Use)" and "LOCUS (Mental Health)". Clinical scoring rules for each instrument are not implemented in this component.
  </Accordion>

  <Accordion title="Reassessment flow">
    When `priorId` is provided, `useLocAssessmentReassess` loads the prior record and seeds the form with its `dimension_scores`. `computeDirection` compares the new total score to the prior total: `step_up` (new > prior), `step_down` (new \< prior), or `lateral` (equal). The new record is linked via `supersedes_id`.
  </Accordion>

  <Accordion title="Assessment status lifecycle">
    New assessments are created with `status: 'draft'`. Signing (via `useSignLocAssessment` on the detail page) sets `status: 'signed'` and records `signed_at` and `signed_by`. If `final_loc_code !== recommended_loc_code`, an `override_reason_code` and `override_rationale` (minimum 20 characters) are required.
  </Accordion>
</AccordionGroup>

## Detail view

This screen displays the detail of a single Level-of-Care assessment record at route `/cl/loc-assessments/:assessmentId`.

### Overview

The LoC Assessment detail page loads a single assessment from the `cl_loc_assessments` table using the `assessmentId` URL parameter. It displays the instrument type (ASAM or LOCUS), the date and time of the assessment, and a status badge (`draft`, `finalized`, or `amended`). The **Summary** tab shows a dimensional profile radar chart and a recommendation card. When a prior assessment exists for the same patient and instrument type, a **Comparison** tab appears showing side-by-side dimension scores. For `draft` assessments, action buttons allow the clinician to accept the computed recommendation or open an override dialog to record a different Level-of-Care with a reason category and rationale.

### Who it's for

Requires the `cl.loc_assessment.view` permission. The **Override** button additionally requires `cl.loc_assessment.override`. The **Accept Recommendation** button additionally requires `cl.loc_assessment.sign`.

### Before you start

* You must hold the `cl.loc_assessment.view` permission for your organization.
* The assessment must exist in the system; navigating to an unknown `assessmentId` renders an "Assessment not found" message with a link back to the list.
* To finalize with an override, you must also hold `cl.loc_assessment.override` and `cl.loc_assessment.sign`.

### Steps

<Steps>
  <Step title="Open an assessment from the list">
    Navigate to `/cl/loc-assessments` and select a record, or follow a direct link to `/cl/loc-assessments/:assessmentId`.
  </Step>

  <Step title="Review the Dimensional Profile">
    On the **Summary** tab, inspect the radar chart showing per-dimension scores. If a prior assessment exists, a previous-score overlay is rendered for comparison.
  </Step>

  <Step title="Review the recommendation card">
    The **Recommendation** card displays the system-computed `recommended_loc` value derived from `computeLocRecommendation`. If a final LoC has been set and differs from the recommendation, the card indicates the assessment is overridden.
  </Step>

  <Step title="Compare with a prior assessment (if available)">
    If a prior assessment exists for the same patient and instrument type, select the **Comparison** tab to view the `LocAssessmentComparisonView` side-by-side display.
  </Step>

  <Step title="Accept the recommendation or override (draft only)">
    For `draft` assessments, either click **Accept Recommendation** to finalize with the computed LoC, or click **Override** (requires `cl.loc_assessment.override`) to open the `LocOverrideDialog`. In the dialog, select a `reason category` and enter a rationale of at least 20 characters, then confirm.
  </Step>
</Steps>

### Key concepts

<AccordionGroup>
  <Accordion title="Instrument types">
    The `instrument_type` field is either `asam` or `locus`. ASAM assessments use six dimensions (`acute_intoxication`, `biomedical_conditions`, `emotional_behavioral_cognitive`, `readiness_to_change`, `relapse_continued_use`, `recovery_environment`). LOCUS assessments use six dimensions (`risk_of_harm`, `functional_status`, `medical_comorbidity`, `recovery_environment`, `treatment_history`, `engagement`).
  </Accordion>

  <Accordion title="Assessment status">
    The `status` field follows the values `draft`, `finalized`, and `amended`. Action buttons for accepting a recommendation or overriding are only visible when `status === 'draft'`.
  </Accordion>

  <Accordion title="Override">
    An override occurs when the `final_loc` set on the assessment differs from `recommended_loc`. An override requires a `OverrideReasonCategory` selection and a rationale string; the database enforces a minimum rationale length of 20 characters.
  </Accordion>

  <Accordion title="Empty / not-found state">
    If the assessment record is not found or does not belong to the current organization, the page renders: "Assessment not found." with a **Back to List** button.
  </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/LocAssessmentListPage.tsx
  * src/cores/cl/hooks/useLocAssessments.ts
  * src/cores/cl/pages/LocAssessmentNewPage.tsx
  * src/cores/cl/pages/LocAssessmentDetailPage.tsx
  * src/cores/cl/types/loc-assessment.ts
</Accordion>