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

# QI Overview

> Quality Improvement project list with search, filters, and summary stats — with full project detail and a creation wizard.

The QI Overview page is the main entry point for the Quality Improvement module. It lists all QI projects with search, category/status filtering, and quick stats. It is located at route `/gr/quality-improvement`.

## Overview

The page is rendered by `QIProjectList` and calls `useQIProjectList` with search and filter parameters. Quick-stats cards (active projects, completed, on hold, total) are sourced from `useQIDashboard`. A **New Project** button opens `QIProjectFormDialog` — no additional permission gate is declared on this route in `gr.tsx`; the wizard route `/gr/quality-improvement/new` also has no gate.

Available categories: `clinical`, `operational`, `safety`, `compliance`, `outcomes`.

Available statuses: `draft`, `proposed`, `planning`, `active`, `on_hold`, `completed`.

## Who it's for

Access follows your organization's role and module configuration.

* No special permission is required to view QI projects.
* Creating a project requires access to the New Project dialog; SME should confirm RBAC expectations.
* The QI module must be enabled (`qi_enabled = true` in Governance Settings).

## Finding a project

1. Go to **Governance & Compliance → Quality Improvement** at `/gr/quality-improvement`.
2. Review summary stats at the top of the page.
3. Use the search bar and Category/Status filters to narrow the project list.
4. Select a project card to open the QI Project Details page.
5. Select **New Project** to create a QI project via the form dialog.

| Concept          | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| QI project       | A structured improvement initiative tracked through lifecycle states   |
| PDSA             | Plan-Do-Study-Act: the methodology used for QI cycles                  |
| Status lifecycle | `draft` → `proposed` → `planning` → `active` → `on_hold` / `completed` |

## Viewing a project

The QI Project Details page (`/gr/quality-improvement/:id`) shows a single Quality Improvement project with full lifecycle management.

The page is rendered by `QIProjectDetail` and loads data via `useQIProjectDetail`. It provides four URL-synced tabs (`overview`, `cycles`, `metrics`, `improvements`) via `useTabUrlState`. Lifecycle actions — **Activate**, **Hold**, **Complete**, **Cancel** — are available from a dropdown menu and execute mutations via `useQIProjectMutation`. Sub-records (PDSA cycles, metrics, improvements) each have their own form dialogs. No permission gate is declared on this route in `gr.tsx`.

Before you start: navigate from the QI Overview page at `/gr/quality-improvement`. A QI project record must exist for the given ID.

1. Go to **Governance & Compliance → Quality Improvement** and select a project.
2. Review the **Overview** tab for title, description, owner, site, category, status, and dates.
3. Open the **Cycles** tab to view and add PDSA cycles; select a cycle to expand its detail.
4. Open the **Metrics** tab to view and record metric measurements.
5. Open the **Improvements** tab to view and add improvement action items.
6. Use the action dropdown to change project status (Activate, Hold, Complete, Cancel).
7. Use **Edit** to open the project form dialog.

| Concept            | Description                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| PDSA cycle         | Plan-Do-Study-Act cycle attached to a QI project                                                                           |
| QI metric          | A measurable indicator tracked over time for a project                                                                     |
| Improvement        | An action item linked to a metric or cycle                                                                                 |
| Status transitions | `proposed` → `active` (Activate), `active` → `on_hold` (Hold), `active` → `completed` (Complete), any → cancelled (Cancel) |

## Creating a project

The New QI Project page (`/gr/quality-improvement/new`) renders `QiProjectWizardPage`, a full-page wizard powered by `ModuleWizardRenderer` (PF-41) that creates a new `gr_qi_projects` record. The QI module must be enabled (`qi_enabled = true` in Governance Settings).

Before you start: have the project title, goal, category, team members, and initial measures identified.

1. Navigate to `/gr/quality-improvement/new` or use the create project action from `/gr/quality-improvement`. The wizard loads from the `qi_project` template.
2. Follow the prompts in `ModuleWizardRenderer`. Steps typically cover project identification, goals, measures, team assignment, and initial PDSA cycle setup.
3. On the final step, submit the wizard. A `gr_qi_projects` record is created.
4. After completion you are navigated to `/gr/quality-improvement`. The new project appears in the list.

**ModuleWizardRenderer (PF-41)** — platform component rendering wizard steps from the `pf_wizard_templates` table.

**qi\_project** — wizard type identifier for QI project creation.

**gr\_qi\_projects** — database table storing QI project records.

**qi\_enabled** — module settings flag; must be `true` for QI functionality to be active.

**PDSA cycle** — Plan-Do-Study-Act improvement cycle created as part of a QI project.

## Related

<Columns cols={2}>
  <Card title="Governance & Compliance" icon="scale-balanced" href="/gr/overview">
    Governance & Compliance core overview.
  </Card>

  <Card title="Governance & parity" icon="clipboard-check" href="/governance/index" />
</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/gr.tsx
  * src/cores/gr/pages/QIProjectList.tsx
  * src/cores/gr/pages/QIProjectDetail.tsx
  * src/cores/gr/hooks/useQIProjectList.ts
  * src/cores/gr/hooks/useQIDashboard.ts
  * src/cores/gr/hooks/useQIProjectDetail.ts
  * src/cores/gr/hooks/useQIProjectMutation.ts
  * src/cores/gr/wizards/qi-project/QiProjectWizardPage.tsx
</Accordion>