Coding Rationale
Purpose
Give the coder/biller a cited rationale draft for the codes already on the claim - never a proposed code.
When to use
After note-context, whenever claim.visit_level or claim.elements exist - triggered by "why is this coded
99214?", "does the note support this diagnosis?", "build the coding rationale", "what backs up this claim?". Also
when the request mixes a rationale with a code change ("bump it to 99215"): build the rationale, decline the change.
When NOT to Use
- Quality-measure status - use quality-gap-check instead.
- Drafting patient or referral documents - use document-derive instead.
- Extracting facts from the note - use note-context instead.
- Submitting the claim - nothing in this plugin submits anything.
Inputs
note_facts with citations; claim.visit_level and claim.elements (each naming the note_facts key that supports it); config/escalation-policy.json; the user's live message.
Steps
- If note_facts are already on the contract with citations, use them; otherwise run note-context first.
- Copy the contract to a working file and append the user's message verbatim to
messages. - 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 decide support yourself. - Read back
coding_rationale.supported[],unsupported_flags[]andchange_requests_refused[]. - Report all three lists verbatim - never move an element from unsupported to supported, and never drop one.
- Escalate every unsupported element to routees.unsupported_claim_element, and every refused code-change request
to routees.code_change_refusal. If the user asked for a code change and
change_requests_refusedis empty, decline it yourself and escalate it the same way. - Present the evidence pack as a draft with
status: "draft"(clinical-doc-rules.md #3). If there is nothing to escalate, say "no unsupported elements - nothing escalated".
Output Format
Contract JSON, sections: coding_rationale = {status: "draft", action_level: "L1", visit_level, supported[{element, type, supported_by, citation{source, locator, text}}], unsupported_flags[{element, type, missing_fact, citation, note_citation}], change_requests_refused[{requested, evidence, citation}], source: "engine:quality_gap_engine"},
then a short bullet list: Supported / Unsupported / Declined. Report only the coding part of the engine output. No
proposed codes appear anywhere. When status is "not_applicable" (no claim), say so and stop.
Example
Supported: 99214 <- moderate_complexity_mdm_documented (Plan, line 10: "...moderate complexity MDM.")
Unsupported: E11.42 - missing neuropathy_documented - escalated to routees.unsupported_claim_element
Declined: "bump the visit to 99215" - this skill never selects or upgrades a code - escalated to routees.code_change_refusal
Grounding requirements
Every 'supported' entry carries the citation of the documented note_fact that supports it; every 'unsupported' flag names the missing fact (clinical-doc-rules.md #4). Do not fabricate or infer supporting documentation, do not treat a requester's assertion or clinical plausibility as evidence, and do not describe an element as supported when the engine did not. If it has no citation, it is unsupported - say so plainly.
Guardrails
Guardrails - all are hard stops:
- Never propose or select a code, and never recommend a higher or lower level.
- Never mark an element supported without a documented, cited note_fact.
- Never silently drop or soften an unsupported flag, however small the dollar value.
- Never present the rationale as final; it is always a draft pending clinician review before submission.
- Never compute support yourself - the engine's result is the result.
Error Handling
- If the engine exits non-zero or writes no output, report "rationale not built: " and stop.
- If a claim element names a note_facts key that is missing, it is unsupported - never look for a substitute fact.
- If the note is unsigned (
halted: "unsigned_note"), report the halt only. - 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
Every unsupported element is escalated by name to routees.unsupported_claim_element, and every refused code-change request to routees.code_change_refusal, in config/escalation-policy.json (clinical-doc-rules.md #6, #7).