[docs] Condition docs: concept, reference, and symptom/diagnosis flows

versioned_docs/version-3.0/concepts/clinical/condition.mdx

@@ -4,73 +4,64 @@ sidebar_position: 3
 
 # Condition
 
-A **condition** is a clinical problem recorded for a patient — a diagnosis, a chronic illness, or a presenting symptom. It is how a patient's diagnoses and problem list are captured, giving every clinician a shared, durable view of what the patient is being treated for.
+## Definition
 
-In the Care product UI, conditions are surfaced as **Symptoms**.
+A **[condition](https://build.fhir.org/condition.html)** is a clinical problem that the care team records for a patient. Care uses one condition record for two things that clinicians enter separately: a **Symptom**, which is what the patient reports or the clinician observes, and a **Diagnosis**, which is what the clinician concludes. A condition is a standing statement about the patient. It stays in the record after the encounter ends, until someone changes its status.
 
-## What it represents
+## Key Attributes
 
-A condition is a *standing statement* about a patient's health, not a one-time reading. A blood pressure value or a lab result is an [observation](../clinical/observation.mdx) — true at the moment it was taken. A condition is a claim the care team is making and tracking: "this patient has diabetes," "this patient presented with chest pain." That claim persists across visits until someone changes its status, which is why a condition needs two things an observation does not — a statement of **how certain** the team is, and a statement of **how the condition is progressing**.
+| Components | What it captures |
+| --- | --- |
+| Symptom or Diagnosis | The coded clinical finding, selected from the Care terminology list. The clinician cannot type free text here. |
+| Status | How the condition progresses over time, from Active to Resolved. |
+| Verification | How certain the care team is about the condition. |
+| Severity | How severe the condition is: Mild, Moderate, or Severe. |
+| Onset Date | The date the condition started. The date cannot be in the future. |
+| Notes | Free text that the clinician adds about the condition. |
+| Encounter | The encounter in which the clinician records the condition. Care attaches the condition to the patient of that encounter. |
+| Recorded by | The user who records the condition, and the date of the record. |
 
-To keep problems comparable across patients and facilities, the condition itself is recorded as a coded clinical finding (drawn from a SNOMED CT vocabulary) rather than free text. Onset, optional severity, the encounter it was noted in, and a free-text note round out the record.
+### Symptom and Diagnosis
 
-## Classification
+Care keeps symptoms and diagnoses in separate lists, and gives each list its own form.
 
-The **category** answers "what kind of problem is this, and where does it live in the record?" Every condition is one of:
+- A **Symptom** is what the patient has. The clinician records a symptom early in the encounter, such as fever or chest pain.
+- A **Diagnosis** is what the clinician concludes. The clinician records a diagnosis for the encounter, such as pneumonia.
 
-- **Problem-list item** — an ongoing problem the care team is tracking for this patient
-- **Encounter diagnosis** — a diagnosis made or confirmed during a specific visit
-- **Chronic condition** — a long-term condition such as diabetes or hypertension, carried across encounters
+The two lists never mix. A symptom that you record stays under **Symptoms**, and a diagnosis stays under **Diagnoses**.
 
-Running alongside the category is a separate axis — the **verification status** — that records certainty. A symptom under investigation might be `unconfirmed`, `provisional`, or `differential`; a settled diagnosis is `confirmed`; something logged in error is `refuted` or `entered_in_error`. Care always requires a verification status, so the record never blurs a working hypothesis with an established fact.
+### Status
 
-## Lifecycle
+Status records the course of the condition. Verification records the certainty of the care team. The two are independent: a condition can be Active and still Provisional.
 
-The **clinical status** tracks where a condition stands over time. It is distinct from verification — that is about how sure the team is; this is about the condition's actual course:
+| Status | Description |
+| --- | --- |
+| Active | The condition is present now, and the care team manages it. |
+| Recurrence | The condition returned after a period without symptoms. |
+| Relapse | The condition returned after remission. |
+| Inactive | The condition is not active now, but nobody resolved it. |
+| Remission | The symptoms decreased, but the condition can return. |
+| Resolved | The condition cleared. |
 
-```text
-active → inactive → remission → resolved
-   ↑         |
-   └─ recurrence / relapse ─┘
-```
+### Verification
 
-- **active** — currently present and being managed
-- **recurrence** — returned after a symptom-free period
-- **relapse** — returned after being in remission
-- **inactive** — no longer active, but not formally resolved
-- **remission** — symptoms have abated, but the condition may return
-- **resolved** — fully cleared
-- **unknown** — current state is not known
+| Verification | Description |
+| --- | --- |
+| Unconfirmed | The care team recorded the condition, but has no evidence yet. |
+| Provisional | The condition is a working answer while the care team continues to examine the patient. |
+| Differential | The condition is one of the possible answers that the care team examines. |
+| Confirmed | The care team has enough evidence for the condition. |
+| Refuted | The care team examined the condition and rejected it. |
+| Entered in Error | A user recorded the condition by mistake. Care keeps the record for audit and hides it from the lists. |
 
-This is not a one-way pipeline. A chronic condition can cycle through active, remission, and recurrence many times over a patient's history.
-
-## How it connects
-
-A condition never stands alone — it is always anchored to a patient and the visit where it was noted:
-
-- **Patient** — the person the condition describes. Care derives this automatically from the encounter, so the condition is always attached to the right record; clients never set it directly.
-- **Encounter** — the visit during which the condition was recorded. Every condition is created in the context of an encounter; chronic conditions can later be re-associated with a new encounter as care continues.
-
-Conditions sit alongside the patient's other clinical records — most closely [allergies and intolerances](../clinical/allergy-intolerance.mdx), which capture a different kind of standing risk, and [observations](../clinical/observation.mdx), which capture point-in-time measurements and findings.
-
-## Permissions
-
-A condition has no permission file of its own — as patient clinical data, it is governed by the **patient** and **encounter** clinical-data permissions a user holds in the relevant facility. Creating, updating, and deleting a condition is gated by write access to the encounter's clinical data; reading it requires the patient's clinical-data permission, falling back to the encounter's clinical-data read permission. Chronic conditions are a special case — updating one is gated by the patient's clinical-data permission rather than the encounter's. Conditions can also be captured by submitting a symptom or diagnosis questionnaire.
-
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_encounter_clinical_data` | Create, update, or delete a condition (the create, update, and destroy paths check write access to the encounter's clinical data; chronic-condition updates are the exception below) | Admin, Doctor, Nurse, Facility Admin |
-| `can_view_clinical_data` | Read a patient's conditions, and update a chronic condition (the read path checks the patient's clinical-data permission; chronic-condition updates check this same permission) | Staff, Doctor, Nurse, Admin, Facility Admin |
-| `can_read_encounter_clinical_data` | Read conditions via an encounter when patient-level clinical access is absent (the read path falls back to this when an `encounter` query param is supplied) | Admin, Doctor, Nurse, Facility Admin |
-| `can_submit_patient_questionnaire` | Submit a patient-subject questionnaire (such as symptom or diagnosis), which can record conditions | Volunteer, Staff, Doctor, Nurse, Admin, Facility Admin, Administrator |
-| `can_submit_encounter_questionnaire` | Submit an encounter-linked questionnaire, which can record conditions | Staff, Doctor, Nurse, Admin, Facility Admin |
-
-Roles are granted to users through facility, organization, or patient memberships, and they cascade down the organization tree — a role held high in the hierarchy applies to the facilities and patients beneath it.
+A clinician cannot select **Entered in Error** for a new record. Care sets this verification when the clinician removes a condition that is already saved.
 
 ## Related
 
-- Reference: [Condition (technical)](../../references/clinical/condition.mdx)
+- Flow: [Record a symptom](../../flows/clinical/record-a-symptom.mdx)
+- Flow: [Record a diagnosis](../../flows/clinical/record-a-diagnosis.mdx)
 - Concept: [Patient](../clinical/patient)
 - Concept: [Encounter](../clinical/encounter.mdx)
 - Concept: [Allergy / intolerance](../clinical/allergy-intolerance.mdx)
 - Concept: [Observation](../clinical/observation.mdx)
+- Reference: [Condition](../../references/clinical/condition.mdx)

versioned_docs/version-3.0/flows/clinical/record-a-diagnosis.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 3
+---
+
+# How to record a diagnosis
+
+## Overview
+
+This flow describes how to record a diagnosis for a patient during an encounter. A diagnosis is one kind of [condition](../../concepts/clinical/condition.mdx) in Care.
+
+## Pre-requisites
+
+- The patient is registered in Care.
+- The patient has an encounter that is open. You cannot record a diagnosis in an encounter that is completed, cancelled, discontinued, or marked as entered in error.
+- You are a member of the facility that owns the encounter.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter related clinical data | Lets you add, change, and remove diagnoses in an encounter. |
+| Can view clinical data about patients | Lets you see the diagnoses that the care team already recorded. |
+
+## Steps
+
+### 1. Open the encounter
+
+1. Open the facility.
+2. Find the patient, and open the encounter.
+
+### 2. Open the diagnosis form
+
+1. Select **Encounter Actions**.
+2. Select **Add Diagnosis**.
+
+You can press `d` instead, while you view the encounter. The `d` shortcut opens the same diagnosis form.
+
+### 3. Select the diagnosis
+
+1. Select **Add Diagnosis** in the form.
+2. Enter the name of the diagnosis in the search box.
+3. Select the diagnosis from the list of results.
+
+Care shows a warning if you select a diagnosis that the list already contains. Change the existing entry instead of adding a second one.
+
+### 4. Complete the details
+
+Set the details of the diagnosis. Care fills the values in the Default column for you.
+
+| Components | What it captures | Default |
+| --- | --- | --- |
+| Onset Date | The date the diagnosis started. You cannot select a date in the future. | Today |
+| Status | The course of the diagnosis, from Active to Resolved. | Active |
+| Severity | How severe the diagnosis is: Mild, Moderate, or Severe. | Moderate |
+| Verification | How certain you are about the diagnosis. Select **Provisional** or **Differential** while you still examine the patient. | Confirmed |
+| Notes | Free text about the diagnosis. | Empty |
+
+Repeat step 3 and step 4 for each additional diagnosis.
+
+### 5. Save the diagnoses
+
+- Select **Submit** to save the diagnoses to the encounter.
+- Select **Save as Draft** to keep your entries and finish later.
+
+## Expected Outcome
+
+- The diagnoses show in the **Diagnoses** list on the **Overview** tab of the encounter.
+- The diagnoses show under **Past Diagnoses** in the clinical history of the patient.
+- Care records your name and the date against each diagnosis.
+
+## Related
+
+Concepts:
+
+- [Condition](../../concepts/clinical/condition.mdx)
+- [Encounter](../../concepts/clinical/encounter.mdx)
+- [Patient](../../concepts/clinical/patient)
+
+Flows:
+
+- [How to record a symptom](./record-a-symptom.mdx)

versioned_docs/version-3.0/flows/clinical/record-a-symptom.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 2
+---
+
+# How to record a symptom
+
+## Overview
+
+This flow describes how to record a symptom for a patient during an encounter. A symptom is one kind of [condition](../../concepts/clinical/condition.mdx) in Care.
+
+## Pre-requisites
+
+- The patient is registered in Care.
+- The patient has an encounter that is open. You cannot record a symptom in an encounter that is completed, cancelled, discontinued, or marked as entered in error.
+- You are a member of the facility that owns the encounter.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter related clinical data | Lets you add, change, and remove symptoms in an encounter. |
+| Can view clinical data about patients | Lets you see the symptoms that the care team already recorded. |
+
+## Steps
+
+### 1. Open the encounter
+
+1. Open the facility.
+2. Find the patient, and open the encounter.
+
+### 2. Open the symptom form
+
+1. Select **Encounter Actions**.
+2. Select **Add Symptom**.
+
+You can press `s` instead, while you view the encounter. The `s` shortcut opens the same symptom form.
+
+### 3. Select the symptom
+
+1. Select **Add Symptom** in the form.
+2. Enter the name of the symptom in the search box.
+3. Select the symptom from the list of results.
+
+Care shows a warning if you select a symptom that the list already contains. Change the existing entry instead of adding a second one.
+
+### 4. Complete the details
+
+Set the details of the symptom. Care fills the values in the Default column for you.
+
+| Components | What it captures | Default |
+| --- | --- | --- |
+| Onset Date | The date the symptom started. You cannot select a date in the future. | Today |
+| Status | The course of the symptom, from Active to Resolved. | Active |
+| Severity | How severe the symptom is: Mild, Moderate, or Severe. | Moderate |
+| Verification | How certain you are about the symptom. | Confirmed |
+| Notes | Free text about the symptom. | Empty |
+
+Repeat step 3 and step 4 for each additional symptom.
+
+### 5. Save the symptoms
+
+- Select **Submit** to save the symptoms to the encounter.
+- Select **Save as Draft** to keep your entries and finish later.
+
+## Expected Outcome
+
+- The symptoms show in the **Symptoms** list on the **Overview** tab of the encounter.
+- The symptoms show under **Past Symptoms** in the clinical history of the patient.
+- Care records your name and the date against each symptom.
+
+## Related
+
+Concepts:
+
+- [Condition](../../concepts/clinical/condition.mdx)
+- [Encounter](../../concepts/clinical/encounter.mdx)
+- [Patient](../../concepts/clinical/patient)
+
+Flows:
+
+- [How to record a diagnosis](./record-a-diagnosis.mdx)