The skill
record-decision-rationaleas its source filesmart-base/L4/skills/smart-l4/record-decision-rationale.mdwrites it, rendered bygen-processes-viz.tsbecause it has no instruction page on this site — do not edit here. All processes
Record a decision rationale (optional)
Skill record-decision-rationale: OPTIONAL and never blocking: a health worker who chooses to may note why they accepted or declined decision-support guidance, in one tap plus an optional coded or free-text reason. Input is the decision; output is one FHIR Provenance (or nothing, when skipped, which is the default). The care plan is updated whether or not this is ever done.
Named by: J3 Verify, import and schedule at the home clinic
Skill id:
record-decision-rationale· Package:authoring-who-smart-guidelines· TaskTask_Rationaleofact-on-decision-support.bpmn(Process_ActOnDecisionSupport), lanehealth-worker, reached only throughEvent_AddReason, a non-interrupting boundary event on the review that happens when the health worker taps “add a reason”.
Opt-in, skippable, and skipped by default. It is never required to finish the review, the visit or the process: the diagram starts it from a non-interrupting boundary event on the review, which takes nothing from the review, so the care plan is updated without waiting for it. A DAK must not make it mandatory; a programme that needs a reason recorded every time is asking for a different, blocking step, and should draw one.
Performed by a person: the health worker who made the decision.
Input and output
The contract is input.schema.json
and output.schema.json.
- In: the
decision(one action’s outcome, fromreview-decision-support-guidance), thepractitioner, and theplanDefinitionthe guidance came from. - Out:
recorded(false when skipped) and, when true, oneprovenance.
The burden
- At most one extra tap: “add a reason”. Choosing a coded reason is the same tap; free text is optional on top.
- No field is required beyond the tap. A rationale with neither code nor text records only that the health worker chose to mark the decision.
Why a Provenance
FHIR R4 Provenance is the lightest
standard artefact that says who decided what, about which guidance, and
why: target the request the decision is about (or the RequestGroup, on a
decline), agent the practitioner, entity (role source) the
PlanDefinition, reason the coded or free-text reason (a CodeableConcept,
whose text carries free text), recorded the time. It adds no workflow
state, unlike a Task; it is not a clinical finding, unlike a DetectedIssue;
and it needs no recipient, unlike a Communication.
When the guidance came as CDS Hooks cards,
the system also sends the service the
feedback its card asks for
(accepted or overridden, with the overrideReason when one was given):
that is the CDS service’s copy, the Provenance is the record’s.
Success criteria
- Skipping it changes nothing anywhere, and the process never waits for it.
- When recorded, the Provenance validates and names the decision’s target, the practitioner and the PlanDefinition.
Input and output contracts
What this skill takes and gives, as a class diagram drawn from its JSON Schema contracts by the schemas viewer’s own renderer. Each box links to its definition; each type to its specification.