prior-authorization-decision-automation

Overview

Provides deterministic code and pipeline recipes for automating prior authorization (PA) workflows: parsing inbound requests, extracting clinical features, applying rules-based adjudication, training machine learning (ML) classifiers, and analyzing denial patterns. Use it when building or debugging X12 278 or FHIR PAS parsers, constructing an adjudication engine, training or explaining a PA decision model, or investigating systemic denial patterns. The skill delivers working code the user deploys in their own pipeline; it does not make or transmit real coverage decisions.

Workflow

<Workflow - Automate a Prior Authorization Task description="Identify the PA task, choose the right approach, and deliver one working code artifact from the reference recipes." tools=[file_read, file_write, run_python] triggers=["parse a prior authorization request", "build a PA adjudication engine", "train a PA decision model", "explain a PA denial", "analyze denial patterns", "any prior authorization automation task"]

1. [Decide] Which PA task does the user need? Match to a reference recipe:

   • Parsing inbound X12 278 or FHIR PAS requests -> references/pa-request-parsing.md
   • Building the feature vector for adjudication -> references/feature-extraction.md
   • Rules-based adjudication -> references/rules-engine.md
   • Training or explaining an ML classifier -> references/ml-classifier.md
   • Analyzing denial patterns or reason codes -> references/denial-analysis.md Validate: Exactly one primary task is identified. If fails: [Ask user] Ask which task they need, listing the five options above.

2. [Decide] If the task is adjudication or model building, choose the approach using <Resource - Automation Approach Selection>. Validate: A rules-engine, ML, or hybrid choice is made and its rationale stated. If fails: [Ask user] Ask how many historical decisions they have and whether the criteria are clear-cut or soft, then re-decide.

3. [Agent] Read the matching reference file (and references/reference-tables.md when the task involves ML hyperparameters or documentation scoring) via file_read. Validate: The reference content loaded and is non-empty. If fails: Report the path that failed and retry once.

4. [Ask user] Confirm the inputs the recipe needs (input format, available data tables, per-payer policy config, output destination if code is to be saved to a file). Validate: The user supplies or confirms the required inputs. If fails: State which input is missing and re-ask.

5. [Agent] Produce one complete working code artifact adapted to the confirmed inputs, following the response structure in (confirm inputs, code, key parameters, gotchas). If the user asked to save it, write it with file_write to the path they gave per Rule 1 and on output destinations. Validate: The artifact is a single self-contained example within the size target and uses only the confirmed inputs. If fails: Trim to one example and re-present.

6. [Decide] Is the artifact sandbox-runnable (parsing, feature extraction, or rules engine) and does the user want it validated?

   • Yes -> [Agent] Run it in run_python against small synthetic sample data to confirm it executes, then report the result. Validate: execution completes without error. If fails: Fix the error and re-run once, or report the blocker.
   • No (ML training or SHAP) -> state that it must run in the user's own environment per Rule 6 and skip execution.

7. [Agent] Close with the applicable gotchas from and the liability reminder from Rule 2. Validate: The response ends with the relevant caveats. If fails: Add the missing caveats.

</Workflow - Automate a Prior Authorization Task>

<Resource - Automation Approach Selection> Look up the row matching the user's situation to choose an approach.

Condition	Approach	Rationale
Clear-cut policy rules (step therapy, age, lab threshold)	Rules engine	Auditable, deterministic, regulatory-safe
Ambiguous cases with soft criteria	ML classifier plus SHAP	Handles nuance; SHAP provides explainability
Fewer than 1000 historical decisions available	Rules engine only	Insufficient data for reliable ML training
Multi-payer deployment	Separate model per payer	Policies differ; cross-payer models fail
Input is X12 278 (EDI)	parse_278() then segment iteration	Pipe-delimited, segment-based
Input is FHIR PAS Bundle	parse_pas_bundle() then resource extraction	JSON, resource-typed entries
</Resource - Automation Approach Selection>

<Resource - Reference Files>

• references/pa-request-parsing.md: X12 278 and FHIR PAS Bundle parsers (standard library, sandbox-runnable).
• references/feature-extraction.md: feature set table and pandas extraction code.
• references/rules-engine.md: deterministic adjudication engine and reason codes.
• references/ml-classifier.md: XGBoost training and SHAP explainability (user's own environment only).
• references/denial-analysis.md: denial pattern analysis and the reason-code reference table.
• references/reference-tables.md: hyperparameter ranges, documentation completeness weighting, and common mistakes. </Resource - Reference Files>