| 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
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.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.- 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
- Read the
assets/flow-template.md gold standard.
- Trace the task through
care_fe, and the permission through care.
- Write to
flows/<domain>/<slug>.mdx.
- Add the doc id to the sidebar file of every version you wrote to.
- Mirror as the conventions describe, then build.
Updating for a product change
- Decide what changed: the steps (UI moved, labels changed), the prerequisites
(permission or configuration), or the outcome.
- Update only the affected sections; preserve the rest.
- 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".
