Generated from smart-base/L4/skills/smart-l4/record-decision-rationale.md — do not edit here.

✎ Edit this page’s source

Record a decision rationale (optional)

Skill id: record-decision-rationale · Package: authoring-who-smart-guidelines · Task Task_Rationale of act-on-decision-support.bpmn (Process_ActOnDecisionSupport), lane health-worker, reached only through Event_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, from review-decision-support-guidance), the practitioner, and the planDefinition the guidance came from.
  • Out: recorded (false when skipped) and, when true, one provenance.

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.

input [1..1]output [1..1]by [1..1]decision [1..1]practitioner [1..1]reason [0..1]provenance [0..1]record-decision-rationale«skill»record-decision-rationaleinput : RecordDecisionRationaleInput [1..1]output : RecordDecisionRationaleOutput [1..1]RecordDecisionRationaleInput«json-schema»RecordDecisionRationaleInputdecision : RecordDecisionRationaleInput.decision [1..1]practitioner : RecordDecisionRationaleInput.practitioner [1..1]planDefinition : string [0..1]reason : RecordDecisionRationaleInput.reason [0..1]RecordDecisionRationaleInput.decision.by«json-schema»RecordDecisionRationaleInput.decision.byreference : string [0..1]display : string [0..1]RecordDecisionRationaleInput.decision«json-schema»RecordDecisionRationaleInput.decisionaction : string [1..1]outcome : "accepted" | "declined" | "modified" [1..1]modified : object [0..1]by : RecordDecisionRationaleInput.decision.by [1..1]at : string [1..1]RecordDecisionRationaleInput.practitioner«json-schema»RecordDecisionRationaleInput.practitionerreference : string [0..1]display : string [0..1]RecordDecisionRationaleInput.reason«json-schema»RecordDecisionRationaleInput.reasoncoding : unknown[] [0..*]text : string [0..1]RecordDecisionRationaleOutput«json-schema»RecordDecisionRationaleOutputrecorded : boolean [1..1]provenance : RecordDecisionRationaleOutput.provenance [0..1]RecordDecisionRationaleOutput.provenance«json-schema»RecordDecisionRationaleOutput.provenanceresourceType : "Provenance" [1..1]

Processes that run this skill

processstep(s) that name it
Act on decision-support guidanceNote the reason (optional)

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev