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

# Patient Submission

> Review a patient-submitted screening instrument response, score result, and individual question answers; mark reviewed or incorporated.

The Patient Submission detail screen displays a clinician-facing view of a single patient-reported screening instrument submission at `/cl/patient-submissions/:submissionId`.

## Overview

The page loads a single patient submission via `usePatientSubmissionDetail`. If `score_result.crisis_detected` is true, a `CrisisResourcesBanner` is rendered at the top of the page. A header row shows the submission type label (`PHQ-9`, `GAD-7`, `AUDIT-C`, `DAST-10`, `C-SSRS Screener`), the `submitted_at` timestamp, and a status badge (`Pending Review`, `Reviewed`, `Incorporated`). A Score Result card shows `total_score`, `severity`, `interpretation`, subscale scores, and a crisis indicator strip when `crisis_detected` is true. A Responses card maps each response key to a human-readable label from `RESPONSE_KEY_LABELS` (covering PHQ-9, GAD-7, C-SSRS, AUDIT-C, and DAST-10 fields). A Review card is shown when `reviewed_by` is set, displaying the `reviewed_at` timestamp. Users with `cl.patient-submissions.review` see action buttons to transition status to `reviewed` or `incorporated`.

## Who it's for

Requires permission `cl.patient-submissions.view` (enforced by `PermissionGate`). Action buttons to mark reviewed or incorporated require `cl.patient-submissions.review`.

## Before you start

* You must have `cl.patient-submissions.view`.
* The submission must exist in `cl_patient_submissions` and be accessible to your organization.
* To mark reviewed or incorporated, you must additionally have `cl.patient-submissions.review`.

## Steps

<Steps>
  <Step title="Open the submission">
    Navigate to `/cl/patient-submissions`, then click a submission row. The detail page loads the screening result, responses, and review state.
  </Step>

  <Step title="Acknowledge crisis indicators (if present)">
    If `score_result.crisis_detected` is true, `CrisisResourcesBanner` is displayed at the top of the page. Address per your organization's crisis protocol before proceeding.
  </Step>

  <Step title="Review the score result">
    The Score Result card shows total score, severity label, and interpretation text. If subscale scores are present, each is listed. A crisis indicator strip appears when `crisis_detected` is true.
  </Step>

  <Step title="Review individual responses">
    The Responses card shows each question key mapped to its human-readable label alongside the patient's answer.
  </Step>

  <Step title="Mark as reviewed (reviewer permission required)">
    If status is `pending_review` and you have `cl.patient-submissions.review`, click **Mark Reviewed** to transition status to `reviewed`.
  </Step>

  <Step title="Mark as incorporated (reviewer permission required)">
    From either `pending_review` or `reviewed` status, click **Mark Incorporated** to transition status to `incorporated`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Submission types and instruments">
    The page supports `phq9` (PHQ-9), `gad7` (GAD-7), `audit_c` (AUDIT-C), `dast10` (DAST-10), and `cssrs_screener` (C-SSRS Screener). Response key labels are predefined in `RESPONSE_KEY_LABELS`; unrecognized keys are formatted by replacing underscores with spaces.
  </Accordion>

  <Accordion title="Status workflow">
    Submissions begin as `pending_review`. From there a reviewer can transition to `reviewed`. From `reviewed` (or directly from `pending_review`), status can be set to `incorporated`. Transitions call `useReviewPatientSubmission`.
  </Accordion>

  <Accordion title="Crisis detection">
    `score_result.crisis_detected` is a boolean on the JSONB `score_result` column. When true, `CrisisResourcesBanner` is rendered above all content and an orange crisis strip appears inside the Score Result card.
  </Accordion>

  <Accordion title="Empty and error states">
    * Load error or submission not found: destructive card with "Unable to load submission." or "Submission not found."
    * No score result: Score Result card is not rendered.
    * No responses: Responses card is not rendered.
    * No review record: Review card is not rendered.
    * Loading: `DetailSkeleton` with header and two card skeletons.
  </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/PatientSubmissionDetailPage.tsx
  * src/cores/cl/hooks/usePatientSubmissionDetail.ts
  * src/cores/cl/hooks/usePatientSubmissionMutation.ts
  * src/cores/cl/types/patient-submissions.ts
</Accordion>