quality-gap-check

Quality Gap Check

Purpose

Produce the objective, ungameable quality-measure result for the encounter, with every status-change request refused and escalated by name.

When to use

After note-context, for every encounter with applicable quality measures, and for every request that asks for a measure status to change - directly ("mark this measure as met") or indirectly ("it was surely done, let it count"). A request to change a status is never a reason to skip this skill - it is exactly when to run it.

When NOT to Use

• Claim evidence for a visit level or diagnosis code - use coding-rationale instead.
• Drafting the handoff or patient documents - use handoff-draft or document-derive instead.
• Extracting note facts - use note-context instead.
• Editing measure definitions - config/quality-measures.json is customer-owned and is never edited by this skill.

Inputs

note_facts with citations; config/quality-measures.json; config/escalation-policy.json; requested_measure_status; request_text; the user's live message(s).

Steps

1. Copy the contract to a working file (never edit the original) and append the user's message verbatim to messages - the engine scans it for override wording.
2. Run the tool: python3 base/scripts/quality_gap_engine.py --question <working.json> --measures config/quality-measures.json --policy config/escalation-policy.json --out <out.json>. Never compute, estimate or adjust a status yourself.
3. The engine marks a measure met only where its required_fact_key is true AND cited, and names the missing_fact (plus the note's own note_citation) for every gap.
4. The engine detects override attempts from requested_measure_status, an uncited note_fact asserted true, or override wording in request_text/messages, refuses each and logs it with the requester's full words. detected_via says where the words came from: "messages" for the live chat message, "request_text" for the request field - one refusal per source, so a chat request is never hidden behind an earlier one. Negated or non-status wording ("don't mark anything as met", "mark it final") is not an override request. A request to report a met measure as a gap is refused too; the measure stays met.
5. Check: if the user's message asks for a status change and override_attempts_refused is empty, do not report a clean result - state the refusal yourself, keep the engine-computed status unchanged (a gap stays a gap and a met measure stays met, in either direction), and escalate it to routees.override_refusal, quoting the words the engine missed (then report the missed wording so the vocabulary can be extended).
6. Report only quality_gap_result (and the escalations that concern measures) verbatim, including every refusal; never restate a gap as met or omit one. Leave coding_rationale to coding-rationale.