care-flow-doc

name

care-flow-doc

description

Use when creating or updating a FLOW doc (the "How do I…?" task layer) for the Care docs site. Trigger when adding a walkthrough for a user task (register a patient, close an encounter, dispense a medication), when a Care UI change alters the steps of an existing task, or when the user says "write a flow for X", "document how to do X", "the steps are out of date", or "this flow is missing". Covers the quality bar (create-patient), the page structure, sourcing steps from care_fe rather than guessing, the manual flow sidebar, link/MDX conventions, the manual flow sidebar, link/MDX conventions, versioning, and build validation.

Building Care flow docs

A flow answers "How do I…?" — it walks a user through one task in the product, start to finish. It is neither a concept (what a thing is) nor a reference (what fields it has). A reader arrives at a flow with a job to do.

Flows live at flows/<domain>/<slug>.mdx under the versioned docs. Follow the shared conventions for which version to author in and how to mirror. One task per page.

A flow is strictly user-facing. Clinicians and operators read it. Never put code, file paths, class names, API endpoints, payloads, database columns or permission slugs in a flow.

The quality bar

The gold standard is the template at assets/flow-template.md. Read it every time. It defines the section names and their order, and they are not negotiable.

flows/clinical/create-patient.mdx is a worked example of the shape, but it predates the template: it uses different headings and still carries an ## API equivalent section. Where it disagrees with the template, the template wins and that page is wrong. Study how a good flow:

• Opens with one sentence naming the task and its end state ("the minimum path from search to a saved record ready for an encounter").
• Pulls the conceptual background out into a :::info Prerequisite admonition linking the concept, so the steps stay uncluttered.
• Separates what you need before you start from the steps themselves.
• Numbers steps as ### 1. <imperative> and keeps each one to a single decision.
• Uses a table when a step has a set of fields, not a wall of prose.
• Ends with what the user can do next.

It also carries an ## API equivalent section. Do not copy that part: flows are now strictly user-facing, and the technical surface belongs in the reference doc.

Naming

The slug is a kebab-case verb phrase: create-patient, close-an-encounter, record-a-symptom. The H1 matches it in sentence case: # Close an encounter. Use the same <domain> folders as concepts and references.

Page structure

Take the structure from assets/flow-template.md. In order:

• Frontmatter: sidebar_position: <n>, then a plain # How to <action> H1.
• ## Overview — one or two sentences saying what the flow does, linking the concept.
• ## Pre-requisites — what must be true before the user starts, in the user's terms. Conditional items start with "If".
• ## Permissions — a | Permission | Access | table, using the human-readable permission name ("Can Create Patient"), never the slug.
• ## Steps — ### 1. <imperative>, one decision per step. Give the real navigation path and the real button labels. Use a table for form fields. Mention a keyboard shortcut only if care_fe/src/config/keyboardShortcuts.json actually defines one for that action.
• ## Expected Outcome — what the user sees, or what the system creates.
• ## Related — concepts and sibling flows.

Do not add an API or payload section. Flows are user-facing; the technical surface belongs in the matching reference doc, which the flow can link to.

Sources

1. care_fe — the flow is a UI walkthrough, so the frontend is primary. Trace the route in src/Routers/routes/, the page component, the form schema, and the navigation labels. Take every user-visible string from public/locale/en.json; enum display labels use keys shaped PREFIX__value (encounter_status__in_progress → "In Progress"). Never print a raw codebase value in a flow.
2. care — for the permission the task needs. Trace the viewset's authorize_* hook to the permission slug the way the concept skill describes, then state it in plain words ("a role with patient create permission"), never as a slug.
3. The matching concept doc — for the framing you link to, not to repeat.

If the UI does not match what you expected, the flow is wrong or the product changed. Report the mismatch; do not write steps you have not verified.

The flow sidebar is manual

This is the easiest thing to get wrong. Concepts and references are autogenerated from their folders, so a new file appears on its own. Flows are not. After adding a flow, append its doc id to the matching domain's items array in the sidebar file of every version you wrote to.

{ "type": "category", "label": "Clinical", "key": "clinical-flows",
  "items": ["flows/clinical/create-patient", "flows/clinical/close-an-encounter"] }

A flow that is not listed there builds cleanly and is invisible on the site.

Linking

Follow the shared link rule, with one trap specific to flows: create-patient is a translated doc, so links to it must be extensionless (../../flows/clinical/create-patient). Every other internal link keeps .mdx. The set of translated docs changes as locales are added — check the current list in the shared conventions rather than assuming.

Workflow

Creating a new flow

1. Read the assets/flow-template.md gold standard.
2. Trace the task through care_fe, and the permission through care.
3. Write to flows/<domain>/<slug>.mdx.
4. Add the doc id to the sidebar file of every version you wrote to.
5. Mirror as the conventions describe, then build.

Updating for a product change

1. Decide what changed: the steps (UI moved, labels changed), the prerequisites (permission or configuration), or the outcome.
2. Update only the affected sections; preserve the rest.
3. Mirror as the conventions describe, build, and report what changed.

Conventions (shared with concept and reference docs)

Read ../care-concept-doc/references/conventions.md before writing for: domains & slugs, the link rule, MDX safety (no {#…} heading ids; wrap { } in backticks), versioning and mirroring, and the npm run build (all locales) gate. That file is the single copy — do not fork a third version of it here, and do not restate its rules.

Language

Write every sentence in ASD-STE100 Simplified Technical English — read ../care-concept-doc/references/ste.md. Flows are the strictest case:

• Steps are commands: "Select Patients.", not "The user should select Patients."
• One instruction per sentence, ≤20 words. Never chain with "and then".
• Condition first: "If the appointment has no linked encounter, select Start Consultation."
• One term for one thing, taken from care_fe/public/locale/en.json.
• Write the user's situation, not the data model: "The patient is registered in Care", not "The patient record exists".