Clinical Task Feature Design¶

FHIR Profile: NexusEmrCoreClinicalTask

This page describes the Clinical Task profile as it is published. It began life as a design proposal and has been brought in line with what shipped: where the two once disagreed — the AI-agent reference model, and the AI-suggestion lifecycle, which did not exist when this was first written — the profile is authoritative and this page now follows it.

Overview¶

The Clinical Task feature provides a comprehensive FHIR Task resource profile designed for clinical workflow management within EMR systems. This profile combines the foundational principles of the original Nexus EMR Task design with enhanced MERT standard compatibility, creating a robust solution for healthcare workflow automation and clinical task management.

Key Capabilities¶

Clinical Workflow Management: Complete task lifecycle from creation to completion
Ownership as Narrowing: Never more than one owner; an absent owner means the whole clinic holds the task, and it stays visible to everyone until somebody narrows it
Conversation Threading: The ask is Task.description; the task's turns are Task.note, oldest first, and are what has been said since
AI Agent Integration: AI agents are named by logical Device reference (identifier-only, no registration), and their suggested writes ride in a contained transaction Bundle
MERT Compatibility: 93% alignment with MERT standard Task requirements
Clinical Safety First: Every task is answerable for -- who asked, who holds it, what was said -- and unassigned work stays in front of everyone rather than waiting to be found

Context and Background¶

Clinical Problem Statement¶

Healthcare workflows involve complex coordination between multiple practitioners, systems, and processes. Traditional approaches often result in:

Lost Tasks: Work items falling through the cracks without clear ownership
Ambiguous Responsibility: Unclear who is responsible for next actions
Poor Audit Trails: Incomplete records of clinical decision-making
System Fragmentation: Tasks scattered across multiple disconnected systems
Manual Overhead: Excessive administrative burden on clinical staff

Solution Approach¶

The Clinical Task feature addresses these challenges through:

Unified Task Model: Single representation for all clinical work items
Explicit Ownership: Responsibility is always locatable - narrowed to a party, or the clinic's collectively and visible to all of it
Complete Audit Trails: Every action timestamped and attributed
System Integration: FHIR-compliant for cross-system interoperability
AI-Ready Architecture: Native support for AI agent integration

Design Principles¶

The Clinical Task design is built on these foundational principles derived from the original Nexus EMR Task specification:

Single Item Type: Only Tasks appear in clinical inboxes - no emails, messages, or notifications as separate entities
Unambiguous Ownership: Never more than one owner. Responsibility is either narrowed to one named party or held collectively by the clinic; it is never split, and never nobody's
Hot Potato Principle: The latest event determines the task's owner and state - who is responsible is always answerable
Complete Audit Trail: Every state change, comment, and action is timestamped and attributed
Clinical Safety First: Task model provides clear audit trails and ownership accountability for patient safety

FHIR Profile Specification¶

Profile Identity¶

Profile: NexusEmrCoreClinicalTask
Parent: Task
Id: nexus-emr-core-clinical-task
Canonical: https://fhir.apps.health/StructureDefinition/nexus-emr-core-clinical-task

Core Requirements¶

Mandatory Fields (Clinical Safety)¶

These fields are required by the profile to ensure clinical safety and accountability:

Field	Cardinality	Rationale
`status`	1..1 MS	Clear lifecycle state for workflow management
`intent`	1..1 MS	`order` \| `proposal` — separates work to do from machine output to decide
`authoredOn`	1..1 MS	Creation timestamp for audit trail
`requester`	1..1 MS	Who initiated the task for accountability
`description`	1..1 MS	The ask: what is wanted and why the task exists, stable for its life
`note`	0..* MS	The conversation that follows the ask — see Conversation Threading

Recommended, not required. Three fields carry a strong expectation the profile deliberately does not enforce, because enforcing it made shapes that legitimately exist unrepresentable:

Field	Cardinality	Expectation
`owner`	0..1 MS	Set when responsibility has been narrowed to a party. Absent means the task is the responsibility of every user in the clinic, and consumers MUST surface it in every default inbox view. See Ownership.
`for`	0..1 MS	Set on every task created from a patient chart. Absent on a standalone work item — an administrative or practice-level to-do that is about no patient. Readers must tolerate the absence rather than treat it as malformed.
`identifier`	0..* MS	Set when the task corresponds to a record in another system. A task born in the EMR has no external record to name and is tracked by its server-assigned id. Machine-written tasks carry a harness key regardless.

Enhanced Fields (MERT Compatibility)¶

Additional fields added for MERT standard alignment:

Field	Cardinality	Purpose
`code`	0..1 MS	Task type classification for workflow routing
`basedOn`	0..*	Authorization/request references (demoted from must-support in 1.17.0 — nothing consumes it)
`groupIdentifier`	0..1 MS	Task batch grouping
`focus`	0..1 MS	What the task is about
`reasonCode`	0..1 MS	Coded rationale for task creation
`performerType`	0..* MS	Required performer type specification

State Machine¶

Task.status binds a required subset of R4's TaskStatus, and these are meanings, not a path. Any state may follow any other, and the ordinary cases prove it: ready straight to completed is a normal day's work, and accepted back to ready is handing something back. There is no flowchart here on purpose.

status	means
`draft`	being composed. In nobody's list yet
`ready`	actionable, in its owner's list. Where the owner is a `CareTeam`, it is in the pool and unclaimed
`accepted`	claimed by its owner, not yet started. Out of common circulation
`in-progress`	actively being worked
`on-hold`	deliberately parked: snoozed, or waiting on something outside this task
`completed`	the work was done
`cancelled`	the work will not be done

accepted earns its place through circulation rather than progress: claiming a pooled task moves owner from the team to the person and takes it out of everyone else's view, which is a real event even though no work has started.

Five base codes are excluded. requested was a second name for ready and the profile used to document them as one state, requested/ready, which is exactly the imprecision this binding removes. received is a fulfilment-chain step this model does not have. failed is a technical outcome rather than a clinical one. entered-in-error has no workflow here that writes it.

And rejected is deliberately absent. A declined proposal is cancelled, the same as one that became moot when its alternative was approved. Those are different clinical records, so statusReason is what tells them apart, and it matters here more than anywhere else on this profile: a proposal cancelled without a reason cannot afterwards say whether a clinician considered it and said no.

Ownership: narrowing, not presence¶

Not yet settled: whether an absent owner is permitted at all

The cardinality of this element is under active review and may change. Permitting an absent owner is new in 1.26.0; the competing position -- that every task names an owner when it is written, with a configured default owner where the producer has nobody to name -- is held by product and is not resolved. It is scheduled to be settled after the September 2026 demo.

What would decide it: whether an obligation exists that every unit of clinical work name an accountable party at all times, and if so whether a work queue, a role or a standing team satisfies it. The relevant EMR certification language requires a task to carry "an assignee (a user or role)", which a CareTeam or PractitionerRole owner meets.

A producer that always sets owner conforms under either outcome. A consumer must handle an absent owner today, and the visibility obligation above holds whichever way the cardinality lands.

owner is 0..1, and both states carry meaning:

`owner`	Meaning
absent	Responsibility has not been narrowed. The task is the responsibility of every user in the clinic.
present	Responsibility is narrowed to exactly one named party.

Assignment is the act of narrowing: a task starts as everyone's and becomes someone's. An absent owner is not "nobody owns it" and not "the owner is unknown" — it is the ordinary state of work that has arrived and not yet been triaged, including work an integration wrote without naming anyone.

owner never repeats. A task held by two parties is held by neither, and the most recent transfer determines who holds it.

The obligation that makes an absent owner safe¶

An absent owner means "everyone's" only if everyone can see it without going to look.

Unassigned work is visible by default, or the model is broken

A system implementing this profile MUST surface unassigned tasks in the default inbox view of every user: present by default, not behind a filter, a tab the reader has to select, or a saved search, and counted wherever a count of outstanding work is shown.

This is part of what an absent owner means, not a UI preference layered on top of it. Without it, an unassigned task is work that exists, that no worklist shows, and that nobody is looking for — which is the failure a mandatory owner was there to prevent.

Established primary-care EMRs solve this with a sentinel: incoming work is stamped with an "unassigned provider" and surfaced through a standing clinic-wide filter or a persistent flag on every user's day sheet. The clinical fact is the same one; what differs is the encoding. This profile represents it as an absent element and places the visibility requirement on the consumer, so that the record does not carry a fictional owner in order to be findable.

One spelling of unassigned¶

The absent element is the only representation. Do not introduce a sentinel owner to keep the field populated:

not a per-tenant CareTeam named "unassigned",
not an Organization standing in for the practice,
not a placeholder Practitioner.

A sentinel reads as narrowed to every consumer that tests whether owner is populated, so un-narrowed work becomes indistinguishable from work a team is actually holding. It also puts two spellings of one state into the estate, and every reader from then on has to know both.

Finding unassigned work¶

Two consequences of representing unassigned as an absent element rather than a value, both worth knowing before you build against it:

Searching. Unassigned tasks are Task?owner:missing=true. :missing is a standard R4 search modifier, but support for it is not universal across servers, and a client depending on it should verify the server honours it rather than reading an empty result as an empty pool. There is no code or reference to match on instead — that is the point of having one spelling.
Subscribing. Not available: this API does not offer the Subscription type to applications at all, so "notify me when a task arrives unassigned" is not expressible as a subscription criterion — and would not be even if it were, because :missing sits outside the criteria vocabulary a subscription surface would use (see Subscriptions). A consumer that must react to arriving unassigned work polls for it. What would decide it: a subscription surface being offered, and :missing entering that vocabulary — two changes, not one, and the second needs the servers implementing it to honour the modifier.

Owner Types¶

owner is typed to PractitionerRole, Practitioner, CareTeam, or Device:

A practitioner — the ordinary case: a named person holds the work.
A practitioner role — the person acting in a capacity, when the capacity is what matters (the on-call physician, the nurse covering a clinic) rather than the individual.
A care team — a standing group holds the work: the nursing pool, the front desk, the referrals desk. The team holds it until a member claims it by becoming the owner.
A Device, meaning an AI-harness graph — an agent holds the work. This is a LOGICAL reference, not a stored resource; see AI agent ownership below.

A CareTeam owner narrows responsibility just as a person does. The cardinality is what buys accountability, not the target type — owner is still exactly one reference when it names a team, and a team that holds a task is a true statement about who has it. The alternative — groupIdentifier naming the work stream while some individual is named as holder — can only say it obliquely: groupIdentifier names the stream, not the holder, so a real person has to be picked in advance to stand in for a queue nobody has picked up yet. That is an accountability fiction. A team owner says the true thing, and a claim is then a real ownership transfer with real Provenance rather than a status change on a task that always named one nurse.

Note the difference between a team owner and no owner: a CareTeam has narrowed the work, to a named and enumerable set of people. An absent owner has narrowed nothing.

groupIdentifier keeps its own job: the batch or requisition a task belongs to. It is not the ownership mechanism.

Note the asymmetry with the conversation. A task can be owned by a CareTeam or a PractitionerRole, but neither can author a turn — R4 permits only Practitioner | Patient | RelatedPerson | Organization as an Annotation.author, and a profile cannot widen it. A writer that reuses the owner reference as the note author will produce an invalid note. See the Task Note profile.

Still deliberately NOT an owner:

An external system. A task waiting on a lab or a partner is owned by the human — or the team — waiting for it, not by the far end. Nothing outside the EMR is going to answer for the delay. Organization is not a permitted target.
Organization is kept closed for a second reason as well: it is the obvious thing to reach for as an "unassigned" sentinel, and admitting it would immediately give the estate two spellings of un-narrowed work. There is a plausible future use for it — a task addressed to another organization, under cross-organization messaging — and that is exactly why it should not be spent on standing in for the practice. What would decide it: a defined cross-organization task-exchange flow, with a stated expectation of who answers for a task once it crosses the boundary.

Ownership Transfer Rules¶

Forwarding — explicit transfer to another party, usually with a note explaining the handoff.
Reply/comment — appending a turn typically hands ownership back to the previous owner. This is what makes a task feel like a conversation and still behave like a queue.
Claim — a member of the owning CareTeam takes individual ownership, moving owner from the team to themselves.
Release — clearing owner returns the task to the clinic: responsibility is un-narrowed again and the task reappears in every user's default view. This is a real transfer and is recorded like any other, not an erasure of one.
Handing to an agent — reassigning owner to a harness graph. This is the resume signal, not a delegation of responsibility: see below.

Every transfer is recorded in relevantHistory (Provenance), independently of whether anyone chose to write a note about it.

Integration Patterns¶

Conversation Threading¶

Conversation Threading is the full treatment: the one mechanism and the three flows that run on it. This section is the profile detail behind it.

The conversation is Task.description and Task.note, and nothing else. The opening body is description, required on this profile: the statement of what is being asked and why the task exists, stable for the life of it. Each note repeat is one turn that followed, typed to the Task Note profile and carrying its own author, time, and markdown text, ordered oldest-first.

note is 0..*, and the ask is not repeated in it. A rendered thread is description followed by the notes in order — the opening body is the first thing a reader sees, not a header above the conversation. The notes are what has been said since.

Task.description   the ask               (stable for the life of the task)
Task.note[0]       the first thing said after it was created
Task.note[1]       a reply, a forward's covering question, a reason for hold
Task.note[n]       ...

A consumer answering "what is this task about" reads description; one answering "what has been said" reads every note. A task with no notes is newly created work that nobody has commented on — an ordinary state, not a malformed record — so a renderer must handle an empty thread. Writers should not copy description into note[0] to fill it: that stores the same statement twice and opens the conversation with something nobody said. Both humans and agents author turns the same way (agents use a logical reference — see below).

Superseded: Communication-based threading

An earlier version of this guide described task conversation as Communication resources linked back to the task, with email-style Message-ID threading. That is superseded. A task's turns are Task.note; Communication is not used for them. The reasons, in short: a turn is not independently meaningful outside its task; "say something and hand it over" is one atomic write rather than two; and a single ordered repeating element needs no threading model at all. What that costs — no per-turn security label, no per-turn Provenance, no structured attachments in a turn — and the additive graduation path if those are ever needed, are recorded on the profile itself.

The thread runs the whole life of the task: opened with the ask, extended at every handoff, still readable when the task is closed and someone asks a year later what happened. That continuity is why turns live on the task rather than in resources that would have to be gathered up.

Notes are what people said; relevantHistory is what happened. They are kept apart on purpose, because an audit trail must not depend on anyone having chosen to comment.

PractitionerRole cannot author a turn

Annotation.author in R4 permits Practitioner, Patient, RelatedPerson, and Organization — not PractitionerRole, even though Task.owner does permit it. A task can therefore be owned by a role while every turn on it is authored by a person, and a writer that reuses the same reference in both places will produce an invalid note. R5 adds PractitionerRole; R4 does not, and a profile cannot widen the list.

AI Agent Integration¶

Clinical Task names an AI agent with a logical Device reference — an identifier, not a resolvable resource. Task.requester and Task.owner carry Reference.identifier under the nexus-harness-graph NamingSystem naming the agent graph, plus Reference.type = "Device". There is no Device resource to register and no Device to fetch: an AI agent is a running graph, not a piece of stored equipment, and requiring a registration step before an agent could act would put a write on the critical path of every invocation.

Task.requester.identifier → NamingSystem/nexus-harness-graph   (Reference.type = "Device")
Task.owner                → the invoking human, until it is handed back to the agent

When an AI agent owns a task:

"Awaiting AI" belongs in the UI. A task held by a graph should read as held by a graph. The Reference.display on the owner is what a surface renders.
Handing a task to an agent does not transfer clinical responsibility. Ownership moves; accountability does not. A surface that presents an agent-held task as "done" is wrong.
Audit rides relevantHistory — the same Provenance chain as any human handoff, with the graph as the agent.
Reassigning owner to the agent Device is the resume signal — it is what makes the harness pick the thread named by the nexus-emr-thread-id extension back up.

Agents in the three places they appear¶

The same logical-reference identity is used in every position, so a reader learns it once:

Position	What it means	Shape
`requester`	The graph that created this task (a suggestion, an answer)	`identifier` under `nexus-harness-graph`, `type = "Device"`
`owner`	The graph currently holding the work — "awaiting AI"	`identifier` under `nexus-harness-graph`, `type = "Device"`
`note.author`	The graph that wrote this turn	`identifier` under `nexus-harness-graph`, no `type`, `display` required

The note.author row is the exception, and the reason is in base R4 rather than in this IG: Annotation.author[x] permits Practitioner, Patient, RelatedPerson, and Organization only. Device is not an allowed target, and a profile cannot add one — profiling constrains, it never widens. So an agent-authored turn is written as an identifier-only logical reference with a display and no literal reference, and Reference.type is omitted rather than set to Device, because asserting that target would claim something the element does not permit. The identifier's system carries the identity: anything under the harness-graph system is a graph, by construction. A consumer that has never read this IG still sees a named author; one that has resolves it to a graph. The nexus-note-agent-author invariant enforces the shape.

Granularity: why a graph and not a model¶

The identity is the graph — the orchestration unit a clinician or auditor can recognise ("chart-update", "scribe") — not the model, the prompt, or the individual agent inside it. Per-agent and per-model trace stays in the harness's own store, where it can change without a spec release. A chart that recorded model versions would be a chart that needed re-profiling every time a model was swapped.

Why no `Device` resource¶

There is nothing to register and nothing to fetch. An AI agent is a running graph, not a piece of stored equipment, and requiring a Device write before an agent could act would put a round-trip on the critical path of every invocation and leave a registry to keep in step with a deployment. The harness's graph registry is the source of truth; the FHIR store carries a reference into it.

Suggested-resource tasks¶

A task carries a suggested chart entry in a contained transaction Bundle -- the same prototype-graph mechanism a reusable template and an SDC form use -- referenced from the pattern-sliced suggestion input (input.type = nexus-task-input-type#suggested-resource). That containment is what MAKES it a suggested-resource task. Neither Task.code nor Task.intent says so, and both are independent axes: a call, an appointment and a review-report can each carry a suggested resource, and a suggested-resource task can be raised as an order.

It is a Bundle rather than a List because dom-2 forbids a contained resource from containing anything, and Bundle is the one container exempt (it derives from Resource, not DomainResource, so it has no contained element for the rule to find). The transaction earns its place beyond legality: entry.request.method is per entry, so one proposal can create one resource and update another, and instantiating is an ordinary POST rather than an algorithm this specification has to define.

Three error-severity invariants hold the shape: nexus-sugg-1 (the reference is local), nexus-sugg-2 (it resolves to a Bundle contained in this same Task), and nexus-sugg-3 (that Bundle is a transaction). All three ship in the published profile and are enforced by the HL7 validator and any conformant external validator.

As of 1.22.0 all three are checked by the TypedFhir runtime validator too. nexus-sugg-2 and nexus-sugg-3 used FHIRPath constructs the emitter could not compile, and were recorded in the library's unverifiable-invariant list rather than answered by weakening the profile; the wider compiled subset takes both. Each is mutation-tested against a clean example, so that "compiles" is not read as "catches". A resource carrying one of these defects now raises an error where it previously produced an invariant-unverifiable note.

The consequence that matters to a consumer: a type-level query cannot see a proposal. A search for MedicationRequest returns no un-approved suggested medication, because it is not a MedicationRequest in the store — it is inside a Task. Nothing has to remember to filter, which is the reason for the containment.

The full treatment is the Suggested-Resource Tasks handbook page — proposal-versus-order, the add/update/retire shapes and how focus tells them apart, the three verbs (approve, accept, instantiate), the evaluation context, cards, citations and the idempotency key. This section is only the part that bears on the Task profile itself.

Lifecycle. Two elements move, and they move independently — which is the whole reason the three verbs are named apart. Task.intent carries the decision; Task.status carries the work:

intent:  proposal  ──approve──→  order            (writes NOTHING to the chart)
                   └──decline──→  status = cancelled + statusReason

status:  ready  ──accept──→  in-progress  ───→  completed
                                        └──instantiate──→  the chart is written

Approve moves intent from #proposal to #order. It is a decision, not a write: the task leaves the Suggestions list for the Tasks list and nothing is created in the chart. A surface that creates the suggested resource here has recorded a Condition or a MedicationRequest that nobody agreed to record.
Accept moves status to accepted and claims the work. Where owner was a CareTeam it becomes the claiming person.
Instantiate is the one that writes: fill the prototypes in and POST the contained transaction Bundle. Traceback rides the shared harness business identifier and Provenance, because the written resource cannot basedOn the Task — most basedOn value sets exclude Task.
Declining is status = cancelled with a statusReason, never rejected, which this profile's binding excludes. The Task and its contained payload are retained: what a machine surfaced and a human declined is part of the record.

Task.intent says what you are being asked to do — it is NOT the suggestion marker. The element binds a required three-code value set:

`intent`	Meaning	The consumer question it answers
`#order`	Authorized work, assigned	"This is mine to do."
`#proposal`	Awaiting a decision	"This is mine to decide."
`#option`	One of a set of alternatives	"This is mine to choose among."

A surface listing "my tasks" almost always wants intent = #order only, and a consumer that ignores intent will present something awaiting approval as though a human had assigned it.

But do not read intent to answer "is this a suggestion?". A suggestion is a task carrying a contained suggested resource, and it can be raised at any of these three intents — including #order, where the suggested entry is already authorized and the task exists to get it recorded rather than decided. The containment is the marker; intent is a different axis. An earlier version of this guide treated intent as the discriminator, and anything built on that reading will misfile #order suggestions.

First pass

Containment is deliberately not a one-way door. If a suggestion ever needs independent identity — its own history, its own search — the graduation path is a first-class resource carrying the same harness business identifier, and the FSH records that as an open valve rather than a closed decision.

External System Integration¶

A task can be about work happening in another system — a requisition sent to a lab, a referral sent to a partner — but an external system is not the owner. owner is typed to PractitionerRole, Practitioner, or Device, and that is deliberate: a task parked on an organization is a task nobody will answer for. The human waiting on the external system keeps it.

Model the external leg instead with:

focus — the chart element the task concerns (the ServiceRequest, the DocumentReference that arrived).
groupIdentifier — the requisition or grouper the external exchange keys on.
identifier — at least one business identifier from the originating system, which is how a returning result is matched back to the task that was waiting for it.
note — what was sent, and what came back.

An "awaiting external" state is a rendering decision on top of status plus who owns it, not a new owner type.

Tasks, the inbox, and the AI harness¶

This section is the whole picture in one place, because implementers arrive at it from three directions and the model only makes sense as a unit.

One rail. There is one kind of work item in the chart: a task. AI suggestions, decision-support recommendations, incoming results needing review, and a colleague's question are all the same resource with the same lifecycle, ownership, and audit. There is no separate "AI inbox", no notification type, no message entity. The inbox is a view over tasks — not a store, and not a second model.

Human work. A person creates a task, writes the ask into description, and assigns it. It moves by reassignment; each move is Provenance in relevantHistory; each thing said is a note. intent is #order, because it is authorized work someone is expected to do.

Agent-created work. A harness graph writes a task with itself as requester, the suggested chart entry in a CONTAINED transaction Bundle, and normally intent = #proposal. The suggested resource is invisible to type-level queries until a human accepts it, so no consumer needs a rule for filtering unapproved machine output — a MedicationRequest search simply does not return one. Instantiating writes the Bundle; declining retains both the task and what was suggested, because what a clinician declined is part of the record.

Talking to an agent. Asking the harness something is not an API call from the chart's point of view: it is a task assigned to the agent, with the question as the opening body. The harness answers by appending a note and handing the task back; a follow-up question is the next note. That means chat history, "go back to that conversation", and worklist counts are all ordinary Task queries, and a conversation with an agent is auditable on exactly the same machinery as a conversation with a colleague.

How an agent notices. The harness is run-scoped: nothing sits waiting between invocations. Assignment is therefore the signal — a task whose owner becomes an agent graph is a task the harness picks up, resuming the thread named by the nexus-emr-thread-id extension. A server-side watcher observes those assignments and starts the run.

Idempotency. A machine-written task carries a business key under NamingSystem/nexus-harness-key, derived from the gap it addresses rather than the run that produced it. A rule that re-runs updates the task it already filed instead of filing a second one, and closes it when the gap closes on its own. Human tasks are unaffected.

What a consuming surface must get right, in order of how badly it goes wrong:

Read intent. Ignoring it means presenting unapproved machine output as assigned work.
Render one owner, whatever its type. owner is exactly one reference and may name a person, a role, a team, or an agent. A surface that assumes a person will mis-render pooled and agent-held work.
Mark agent turns. A turn whose author is under the harness-graph system is machine-authored and should read that way.
Read from the FHIR store. Not from the harness. The store is the record; the harness thread is working memory.

Use Cases and Workflows¶

1. Lab Result Review¶

Scenario: CBC results arrive with abnormal values requiring physician review

Workflow:

Lab system creates NexusEmrCoreClinicalTask with:
- code: "lab-review"
- owner: Dr. Smith (ordering physician)
- reasonReference: DiagnosticReport
- priority: "urgent" (abnormal values)
Dr. Smith reviews results and adds a comment as a new Task.note turn
Task completed with outcome documented

Example Task:

{
  "resourceType": "Task",
  "status": "ready",
  "code": {"text": "Lab Result Review"},
  "owner": {"reference": "Practitioner/dr-smith"},
  "for": {"reference": "Patient/john-doe"},
  "reasonReference": [{"reference": "DiagnosticReport/cbc-001"}],
  "priority": "urgent"
}

2. AI-Assisted Triage¶

Scenario: Patient message requires triage with AI assistance

Workflow:

Patient portal creates task for message review
Triage nurse forwards to the AI agent for initial assessment — owner becomes the logical Device reference naming the agent graph, which is the signal that resumes the thread
AI agent processes the message and provides a summary; anything it proposes to write to the chart comes back as a contained suggestion on its own review Task
Nurse reviews the AI recommendation and accepts or rejects it

Ownership Flow:

Patient Message → Triage Nurse → AI Agent → Triage Nurse → Final Action

3. Referral Management¶

Scenario: Cardiology referral needs processing and follow-up

Workflow:

Physician creates referral task
MOA processes referral, forwards to external system
External system (specialist office) acknowledges receipt
Appointment confirmation completes the task

Task Hierarchy:

Parent: Referral Management
├── Child: Process Referral (MOA)
├── Child: External Acknowledgment
└── Child: Appointment Booking

Clinical Task Feature Design¶

Overview¶

Key Capabilities¶

Context and Background¶

Clinical Problem Statement¶

Solution Approach¶

Design Principles¶

FHIR Profile Specification¶

Profile Identity¶

Core Requirements¶

Mandatory Fields (Clinical Safety)¶

Enhanced Fields (MERT Compatibility)¶

State Machine¶

Ownership: narrowing, not presence¶

The obligation that makes an absent owner safe¶

One spelling of unassigned¶

Finding unassigned work¶

Owner Types¶

Ownership Transfer Rules¶

Integration Patterns¶

Conversation Threading¶

AI Agent Integration¶

Agents in the three places they appear¶

Granularity: why a graph and not a model¶

Why no Device resource¶

Suggested-resource tasks¶

External System Integration¶

Tasks, the inbox, and the AI harness¶

Use Cases and Workflows¶

1. Lab Result Review¶

2. AI-Assisted Triage¶

3. Referral Management¶

Why no `Device` resource¶