> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/checklists/checklist-scores.md).

# Checklist scores

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/checklist-scores.md).
{% endhint %}

**Checklist scores** are the numbers Snapfix shows about a **checklist** while it is being filled in: the **completed** count and percentage, and how many items got each answer (pass, flag and fail; yes and no), each with its share. A checklist has no single overall score. The numbers show on the task's checklist card, in its summary and in the task report, so that a manager can see how far a check got and how it went. They are worked out from the items each time they are shown; no table stores them and no endpoint returns the summary.

## Rules

* **Completed** is the number of ticked items. Its percentage is the ticked items out of all items, leaving out sections marked NA and sections without items, rounded to a whole number. The card's ring shows it, and on the web each section card shows its own percentage the same way ([Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md#rules)).
* **Sections marked NA** are left out of the completed percentage and of every share ([Summary](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md#summary)). On the web the section's NA switch has no label.
* **Pass, flag and fail shares** are each answer's count divided by the items that take a pass, flag or fail answer, leaving out items answered NA. The base includes items nobody has answered yet \[[ASK-69](https://github.com/snapfix/docs/blob/main/ASK.md#ask-69-should-the-pass-flag-fail-yes-and-no-shares-count-unanswered-items)]. An NA answer still counts in the completed count when the item is ticked.
* **Yes and no shares** are each answer's count divided by all the yes or no items, also counting unanswered ones \[[ASK-69](https://github.com/snapfix/docs/blob/main/ASK.md#ask-69-should-the-pass-flag-fail-yes-and-no-shares-count-unanswered-items)].
* A checklist with both kinds of items has two separate bases, one per kind.
* Ratings and notes are not counted in any share ([Summary](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md#summary)).
* **Shown as** a count with its share in brackets, such as "3 (42.86%)". Shares have two decimals; 100 shows without decimals (web\_app\_v2 @ 0989b8e685, `src/app/pages/task/task-checklist/task-checklist-summary/task-checklist-summary.component.ts:56-61`).
* **When the summary shows.** The web shows "Checklist Summary" once at least one pass, flag, fail, yes or no answer is given; its pass, flag and fail row appears with the first such answer, and its yes and no row with the first yes or no. iOS and Android show their scores as soon as the checklist has such items, before any answer ([Summary](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md#summary)).
* On the web the ring and the summary show to everyone who can open the task. They are hidden on planned tasks, and the summary is hidden in the housekeeping drawer ([Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md#layout); web\_app\_v2 @ 0989b8e685, `src/app/pages/task/task-checklist/task-checklist.component.html:7`, `:73-80`).
* The web recounts on every change. Android counts its "Checklist Scores" footer only when the list is scrolled to its end, and hides the footer elsewhere (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/ViewCheckListActivity.kt:1634-1648`, `:1961-1963`).
* A task that shows only its template's items (a checklist not yet started) is scored on the screen from those items. The task lists of the Site Console report it as 0%, because the server counts only a task's own items ([Checklist job object](https://docs.snapfix.com/engineering-reference/api/checklists.md#checklist-job-object)).
* The group rule "Checklist must be 100% before set to Green" reads the item count. After the web's checklist dialog closes, the value it reads is the completed count, so a checklist with nothing ticked can turn green ([Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md#automatic-status)).

## Flow

```mermaid
flowchart LR
  item["Item ticked or answered"] --> done["Completed: ticked items out of the counted items"]
  item --> pff["Pass, flag, fail: answers out of the items that take them, NA answers left out"]
  item --> yn["Yes and no: answers out of the yes or no items"]
  na["Section marked NA"] -. "left out" .-> done
  na -. "left out" .-> pff
  na -. "left out" .-> yn
  done --> ring["Card ring and the completed line"]
  pff --> rows["Summary rows"]
  yn --> rows
```

## Platforms

| Capability                            | Web                                               | iOS                                  | Android                                |
| ------------------------------------- | ------------------------------------------------- | ------------------------------------ | -------------------------------------- |
| Completed percentage                  | Ring on the card; each section card in the dialog | Circle at the top                    | Header of the screen                   |
| Completed count                       | "Completed N (P%)" in the summary                 | "Completed N (P%)" in the score card | "Completed N (P%)" in the score footer |
| Pass, flag and fail counts and shares | Yes, once such an answer exists                   | Yes                                  | Yes, in the "Checklist Scores" footer  |
| Yes and no counts and shares          | Yes, once such an answer exists                   | Yes                                  | Yes, in the footer                     |
| Shown before any answer               | No                                                | Yes                                  | Yes                                    |
| Ratings in the scores                 | No                                                | No                                   | No                                     |
| Recount                               | Every change                                      | Not traced                           | When the list is scrolled to its end   |

## Screens

* [Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md): the ring, the summary card on the web, the score card on iOS and the "Checklist Scores" footer on Android.
* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md): the checklist card, and the task report, which includes the checklist summary.

## API and data

* No endpoint returns the summary. The web counts the items from [GET /v1/app/todos](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1apptodos); the apps count their device copy. The answers come from [PUT /v1/app/todos/{uuid}](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1apptodosuuid) and the ticks from [PUT /v1/app/todos/check/{uuid}](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1apptodoscheckuuid).
* The Site Console's task lists get each task's percentage from the server as `checklistPercent` ([Checklist job object](https://docs.snapfix.com/engineering-reference/api/checklists.md#checklist-job-object)).
* Checklist reports: the [Reports API](https://docs.snapfix.com/engineering-reference/api/reports.md) builds the Excel checklist report for the apps (`checklist_report`) and the web (`checklist_report_excel`).
* Tables: [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) holds the counted columns: `fDone`, the answers (`radioPassValue`, `radioFollowUpValue` for the flag, `radioFailValue`, `radioNaValue`, `yesnoValue`), the answer types (`radioEnable`, `yesnoEnable`) and the section NA columns (`sectionNaEnable`, `sectionNaValue`). A template's items, counted before the checklist is started, are in [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md).

## Depends on

* [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md): the ticks and answers being counted.
* [Checklist templates](https://docs.snapfix.com/product/features/checklists/checklist-templates.md): the answer types and NA sections a checklist has.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Groups](https://docs.snapfix.com/product/features/groups/groups.md): the 100% rule for green.
* [Task reports](https://docs.snapfix.com/product/features/reports/task-reports.md): the checklist summary inside the task report.

## Edge cases

* **No answers yet:** the web shows no summary; the apps show the score rows with zeros.
* **Unanswered items:** they stay in the base of every share and lower it \[[ASK-69](https://github.com/snapfix/docs/blob/main/ASK.md#ask-69-should-the-pass-flag-fail-yes-and-no-shares-count-unanswered-items)].
* **Only NA answers:** the pass, flag and fail shares are 0; on the web the row doesn't show, because no pass, flag or fail answer exists.
* **Empty checklist:** 0%, with no summary.
* **Offline (apps):** the scores come from the device's copy, so they change before the server has the answers.
* **Planned tasks and the housekeeping drawer (web):** see [Rules](#rules).
* **Time zones and integrations:** none for scores.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/checklists/checklist-scores.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
