denial-classify

Denial Classify

Purpose

Establish what kind of denial this is, from the denial document itself, before anything else runs.

When to use

Use at the start of every denial/appeal run, on receipt of a denial letter or remittance advice (X12 835 or its paper equivalent) - typical asks are "we got a denial from Contoso dated 8/20", "what kind of denial is this", "read this EOB and start the appeal".

When NOT to Use

Do NOT use when: the denial has already been classified on the contract (go straight to policy-retrieve); the question is about a pre-service prior-authorization denial - use the prior-auth-assist plugin instead; the ask is to draft or reword the appeal letter - use appeal-draft instead; the ask is to find chart documentation - use evidence-assemble instead; the ask is to interpret payer policy language or compute the deadline - use policy-retrieve or deadline-track instead; or no denial document is available - there is nothing to classify from and guessing is not permitted.

Inputs

Denial letter or remittance advice (X12 835 or paper equivalent), read with the session's file-reading tool (e.g. ReadFileContent for a OneDrive/SharePoint file); original claim and coding (837) when supplied; config/payer-appeal-windows.json for the appeal level.

Steps

1. Read the denial document and copy verbatim: payer (835 N1PR), claim_id (CLP01), claim_value (CLP03), paid amount (CLP04), adjustment group, reason code and amount (CAS01/02/03), remark codes (claim-level MIA/MOA or service-level LQHE - record which segment), and original_code (837 SV1/SV2; if no 837 is supplied, the 835 SVC echo, disclosed as such).
2. Set denial_date to the date printed on the letter/remittance (835: DTM*405). If the document carries more than one candidate date and they differ, leave denial_date unset and escalate - the rule for which date starts the appeal window is [TO CONFIGURE: payer-specific rule for which date starts the appeal window]. Set as_of to today's date (the date this classification was performed).
3. Set recoverable_value from the remittance amounts only (CLP03 minus CLP04, cross-checked against CAS03); if they disagree, leave it unset for a human.
4. Classify the denial type from the extracted codes (e.g. medical necessity, timely filing, coding, authorisation missing) - never from what the requester says the denial is.
5. Set the appeal route to the payer's configured level from config/payer-appeal-windows.json payers[payer].level; if the payer is not configured, record "not configured" and let deadline-track escalate.
6. Record the source document (name and date) and the source segment for every field, write denial{} to the contract as the entry hop, and hand off to policy-retrieve.