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

# Scorecards

> View, create, and manage weekly scorecards — enter metric values, record trends, and submit or approve scorecards by role and week.

The Scorecards screen is accessible at `/lo/scorecards` and provides a weekly view of scorecards, filterable by role, with previous/next week navigation.

## Overview

The `ScorecardsPage` loads all scorecards via `useScorecards`, active metrics via `useScorecardMetrics`, and role definitions via `useRoleDefinitions`. The default week is the current week starting on Monday (`startOfWeek` with `weekStartsOn: 1`). Users navigate between weeks via previous/next chevron buttons. A role filter (defaulting to "all") narrows the list. Scorecards are filtered client-side to the selected week and role. Status badges display draft (muted), submitted (info), and approved (success) states using semantic color classes. The `useScorecardMutation` hook's `create` method is called when creating a new scorecard.

## Who it's for

Requires `LO_PERMISSIONS.DASHBOARD_VIEW` (`lo.dashboard.view`) via the shared `LOViewGuard`. Editing scorecards requires `lo.scorecard.edit`.

## Before you start

* `lo.dashboard.view` permission required.
* Scorecard metrics must be configured (see Scorecard Metrics screen).
* Roles must be defined in the Accountability Chart.

## Steps

<Steps>
  <Step title="Navigate to Scorecards">Go to `/lo/scorecards`. The page loads scorecards for the current week.</Step>
  <Step title="Filter by role">Select a role from the dropdown to filter scorecards to that role.</Step>
  <Step title="Navigate weeks">Use the left/right chevron buttons to move to previous or next weeks.</Step>
  <Step title="View a scorecard">Select a scorecard card to navigate to `/lo/scorecards/:scorecardId` for detail and editing.</Step>
  <Step title="Create a scorecard">Select the "+" button to create a new scorecard for the selected week.</Step>
</Steps>

## Key concepts

* **Week start**: Monday (`weekStartsOn: 1`), formatted as `yyyy-MM-dd`.
* **Status**: `draft`, `submitted`, `approved` — displayed with semantic color tokens.
* **Roles with metrics**: only roles that have at least one active scorecard metric are shown in the role filter.

## Creating a scorecard

The path `/lo/scorecards/new` is not defined in `src/routes/lo.tsx` and is not a standalone screen. Scorecard creation is triggered inline from the `/lo/scorecards` page using the `useScorecardMutation` `create` method, which creates a scorecard for the currently selected week and role. The `:scorecardId` parameter route would match `/lo/scorecards/new` with `new` as the ID, resulting in an empty or loading state.

To create a scorecard: go to `/lo/scorecards`, select the week and role, then select "+" to create a new scorecard.

## Viewing a scorecard

The Scorecard Details screen is accessible at `/lo/scorecards/:scorecardId` and allows users to enter actual metric values, record trend directions, add notes, and transition the scorecard from draft to submitted or approved.

The `ScorecardDetailPage` fetches the scorecard via `useScorecard` and the associated metrics via `useMetricsByRole`. It initializes a local `values` state from existing scorecard values, mapping each metric to its `actual_value`, `trend`, and optional `notes`. The `ScorecardValueEditor` component renders an input for each metric. On save, `bulkUpsert` from `useScorecardValueMutation` persists all changes. A "Submit" button transitions the scorecard status to `submitted` via `updateStatus`. An "Approve" button transitions it to `approved`. The entity breadcrumb shows the role name and "Scorecard".

Permissions: `lo.dashboard.view` required; editing values requires `lo.scorecard.edit`. The scorecard identified by `:scorecardId` must exist, and metrics must be configured for the scorecard's role.

1. Open a scorecard: navigate to `/lo/scorecards/:scorecardId` or select a scorecard from the Scorecards list.
2. Enter metric values: for each metric, enter the actual value, select a trend direction, and optionally add notes via `ScorecardValueEditor`.
3. Save changes: select Save to persist all values via `bulkUpsert`.
4. Submit: select Submit to transition the scorecard status from `draft` to `submitted`.
5. Approve: select Approve to transition the status to `approved` (available when submitted).

**Key concepts:**

* **Status flow**: `draft` → `submitted` → `approved`.
* **TrendDirection**: the trend field on each metric value; default is `same`.
* **bulkUpsert**: a single mutation call that persists all metric values for the scorecard at once.

## Related

<Columns cols={2}>
  <Card title="Leadership" icon="compass" href="/lo/overview">
    Leadership core 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/lo.tsx
  * src/cores/lo/pages/ScorecardsPage.tsx
  * src/cores/lo/pages/ScorecardDetailPage.tsx
  * src/cores/lo/hooks/useScorecards.ts
  * src/cores/lo/hooks/useScorecardMetrics.ts
  * src/cores/lo/hooks/useRoleDefinitions.ts
  * src/cores/lo/hooks/useScorecardValues.ts
</Accordion>