Handoff Draft
Purpose
Give the next clinician a clear, cited handoff including every open quality gap and unsupported claim element.
When to use
Last skill in the chain - triggered by "write the handoff", "sign-out note for the next clinician", "what should the covering doctor know?", "hand this over to the night team". Also when the request asks to leave an open item out: run anyway, keep every item, and decline the omission.
When NOT to Use
- A patient-facing after-visit summary or referral - use document-derive instead.
- Computing measure status - use quality-gap-check instead.
- Building or explaining claim evidence - use coding-rationale instead.
- Extracting facts from the note - use note-context instead.
- Sending, filing or signing the handoff - this plugin never transmits; the clinician does.
Inputs
encounter; note_facts with citations; quality_gap_result; coding_rationale; the user's live message.
Steps
- Copy the contract to a working file and append the user's message verbatim to
messages. - Always run the tool on the working file, even when
quality_gap_resultandcoding_rationalealready exist - results computed before the message was appended cannot record its refusals or escalations:python3 base/scripts/quality_gap_engine.py --question <working.json> --measures config/quality-measures.json --policy config/escalation-policy.json --out <out.json>. Draft from<out.json>only. - If
quality_gap_result.haltedis "unsigned_note", write no handoff: restate the halt and stop. Ifcoding_rationale.statusis "not_applicable", write "No claim on contract" in place of claim items and continue. - Draft the clinical summary from encounter and cited note_facts only.
- List every
quality_gap_result.gapsentry and everycoding_rationale.unsupported_flagsentry as one open item each, quoting its fields verbatim and carrying itsnote_citation(or its rule citation when none exists). - Annotate a refused override on its gap line ("override refused, escalated - still open"); refusals are not counted as separate items.
- If
omission_requests_refusedis non-empty, or the user asked to leave an item out, add one line: "Request to omit declined - every open item stays listed" (escalated to routees.omission_refusal). - Write
handoff_note = {"status": "draft", "action_level": "L1", "text": ..., "citations": [...]}for clinician review before it is sent.
Output Format
Contract JSON: handoff_note = {status: "draft", action_level: "L1", text, citations[]} where text has two
sections: "Clinical summary" (bullet per cited fact) and "Open items (N = gaps + unsupported flags)" (one bullet per
item). The open-item count always equals gaps + unsupported_flags. Status is always "draft".
Example
Open items (2 = 1 gap + 1 unsupported flag)
1. QUALITY GAP diabetic_foot_exam - missing foot_exam_documented [full note reviewed] - override refused, escalated - still open
2. UNSUPPORTED E11.42 - missing neuropathy_documented [clinical-doc-rules.md #4] - escalated to routees.unsupported_claim_element
Grounding requirements
Every open item matches a quality_gap_result.gaps or coding_rationale.unsupported_flags entry verbatim, with its citation, and every clinical statement traces to a cited note_fact. Do not fabricate follow-up, timing, resolution or reassurance that the contract does not contain, and never describe a gap as "addressed", "likely done" or "pending closure" when the engine calls it a gap. If the user asks what to do "before tomorrow" and the contract has no dates, say that no dated follow-up is documented.
Guardrails
Guardrails - all are hard stops:
- Never omit an open item to make the handoff look cleaner, shorter or more favourable.
- Never mark the handoff as final, and never transmit, file or sign it.
- Never soften an open item's wording or merge several into one vague line.
- Never add a finding, plan or outcome that is not on the contract.
Error Handling
- If the engine exits non-zero, report "handoff not drafted: gap check failed ()" and stop.
- If note_facts are missing, run note-context first; if it halts, report the halt.
- Never draft open items from memory when the engine output is unavailable.
- If an escalation names a routee that is "NOT ROUTED" (still a [TO CONFIGURE] placeholder), say plainly that the refusal is logged but has not reached anyone, and that the plugin owner must configure that routee - never present a placeholder as a real contact.
Escalation / uncertainty
If any measure remains a gap, the handoff names it as unresolved; refused overrides stay escalated to routees.override_refusal and refused omissions to routees.omission_refusal (clinical-doc-rules.md #6, #7).