Use this skill when the task involves a Northstar Health Plan payer-operations work item: prior authorization nurse review, pharmacy coverage appeals, payment-integrity claim repricing, peer-to-peer authorization closure, or therapy-margin queue analysis. The target environment is a shared read-only payer-operations service that exposes REST business endpoints and an SQL query interface.
Environment
The task prompt supplies a base URL (e.g. <TASK_ENV_BASE_URL>). Substitute
that value for {BASE} below when constructing requests.
Authentication. Every SQL request uses the bearer token provided in the
task prompt (typically pa-review-token-014):
Authorization: Bearer {TOKEN}
Available endpoints.
| Method | Path | Purpose |
|---|---|---|
| GET | {BASE}/ |
Portal landing page |
| GET | {BASE}/health |
Service health and DB presence |
| GET | {BASE}/api/tables |
Full schema listing (table names, columns, keys, nullability) |
| GET | {BASE}/api/cases |
All case records |
| GET | {BASE}/api/cases/{case_id} |
Single case |
| GET | {BASE}/api/policies |
All policy records |
| GET | {BASE}/api/policies/{policy_id} |
Single policy |
| GET | {BASE}/api/documents/{document_id} |
Single document |
| GET | {BASE}/api/rate-schedules |
All rate schedule / benchmark records |
| GET | {BASE}/api/appeals |
All appeal records |
| POST | {BASE}/sql/query |
Arbitrary read-only SQL (JSON body with "sql" key) |
The SQL interface returns JSON shaped as {"columns": [...], "rows": [...], "row_count": N, "limited": bool}. Use it for cross-table joins and targeted
queries; fall back to REST endpoints when you need a single record or simple
listing.
Do not inspect environment source files, generated data files, SQLite files, manifests, or setup scripts. Use only the REST endpoints and the SQL endpoint listed above.
Database schema
The tables available in the environment are:
cases— case header:case_id,member_id,provider_id,request_type,service_domain,policy_id,request_date,due_date,current_stage,current_status,urgency,summarymembers— member demographics:member_id,patient_name,dob,plan_id,plan_type,product,employer_group,member_statusproviders— provider details:provider_id,provider_name,specialty,npi,phone,fax,organizationplans— plan info:plan_id,payer_name,plan_type,state,network,effective_start,effective_end,notesdocuments— clinical/admin documents:document_id,case_id,document_type,document_date,received_date,source_system,is_current(1 = current, 0 = stale),title,summarydocument_facts— structured facts from documents:fact_id,document_id,case_id,fact_key,fact_value,numeric_value,unit,supports_criteria(criterion ID or null)request_lines— requested service lines:line_id,case_id,cpt_code,modifier,service_name,requested_units,requested_start,requested_end,diagnosis_codes,billed_chargeauthorizations— auth records:auth_id,case_id,auth_number,status,approved_units,approved_start,approved_end,approved_cpt(comma-separated list),approved_modifier,denial_reasonpolicies— policy definitions:policy_id,policy_name,version,effective_start,effective_end,precedence,summarypolicy_criteria— individual criteria:criterion_id,policy_id,criterion_key,criterion_text,approval_required(1/0),result_if_missing(deny/pend/uphold/correct)case_criteria— criteria evaluated per case:case_id,criterion_id,result,evidence_fact_ids,gap_description,reviewer_scopeappeals— appeal records:appeal_id,case_id,denial_date,received_date,appeal_type_requested,appeal_path,expedited_attestation,appeal_deadline,outcome,owner,notesdrug_trials— formulary failure trials:trial_id,case_id,medication,outcome,documented(1/0),start_date,end_date,notesassistance_screen— manufacturer assistance:case_id,program_name,income_percent_fpl,insurance_type,denial_required,denial_on_file,missing_fields(comma-separated),assistance_statusclaims— claim headers:claim_id,member_id,case_id,payer,received_date,claim_status,auth_number,billed_total,paid_totalclaim_lines— claim line items:claim_line_id,claim_id,line_number,cpt_code,modifier,units,billed_amount,paid_amount,denial_code,service_datepayment_benchmarks— rate schedules:benchmark_id,payer,plan_type,service_domain,cpt_code,modifier,effective_start,effective_end,allowed_amount,source_name,source_versionp2p_events— peer-to-peer discussions:p2p_id,case_id,scheduled_at,duration_minutes,provider_argument,new_information,outcome,final_status,reviewer,notesservice_margin— monthly margin:month_id,period,payer,payer_segment,service_domain,cpt_code,visits,net_revenue,variable_cost,fixed_cost_allocated,charge_sensitive
Use GET /api/tables to refresh the schema in case of environment updates.
General workflow
Follow this sequence for every payer-operations task:
Read the input. Open
input/prompt.txtfor the task description andinput/payloads/task_context.jsonfor the target business ID, role, reporting date, and any domain-specific memo. Openinput/payloads/answer_template.jsonto get the required output shape, allowed enum values, field definitions, and ordering rules.Gather environment records. Use the SQL endpoint or REST endpoints to retrieve every record linked to the target business ID. At minimum pull:
- The case record from
cases - The member record from
members - All documents from
documents(pay attention tois_current) - All document facts from
document_facts(notesupports_criteria) - All request lines from
request_lines - All case criteria from
case_criteria - The authorization record from
authorizations - The policy criteria from
policy_criteriajoined through the case'spolicy_id - Any domain-specific tables:
drug_trials+assistance_screenfor drug appeals,claims+claim_lines+payment_benchmarksfor payment integrity,p2p_eventsfor P2P,service_marginfor finance queues,appealsfor appeals
- The case record from
Evaluate against criteria. Compare the
case_criteriaresults anddocument_factsagainst the policy criteria. Identify which criteria are met, not met, unclear, or not applicable. Note gaps and exceptions:- Stale documents (
is_current = 0) that should be excluded - Undocumented or insufficient evidence
- Missing packet items
- Charge-sensitive rows in margin queues
- Stale documents (
Determine source precedence. Select the
source_precedencerule that matches the task domain:Precedence When to use current_clinical_records_over_stale_exportUM nurse review, PT prior auth — current clinical documents take priority over stale history payer_appeal_before_manufacturer_assistancePharmacy appeals — resolve the payer appeal path before manufacturer assistance effective_benchmark_by_plan_modifier_and_datePayment integrity / claim repricing — select the benchmark effective on the service date for the correct plan type and modifier new_patient_specific_p2p_informationPeer-to-peer authorization — P2P discussion and its new information takes precedence margin_threshold_then_charge_sensitivityFinance / margin queue — flag below-threshold rows first, then charge-sensitive rows appeal_deadline_then_clinical_then_payment_integrityCombined appeal + payment integrity tasks Build the answer. Start from the answer template shape and populate every required field. Follow all ordering rules, enum choices, numeric precision, and date formatting constraints in the template. Keep the JSON strict — no comments, no prose outside the JSON object.
Verify the basis audit. Every answer includes a
basis_auditobject:source_precedence— the rule from step 4controlling_record_ids— environment record IDs that directly control the result, listed in operational evidence orderexception_record_ids— records explaining exclusions, denials, gaps, or missing information; list criteria/route gaps before stale/excluded records when both appearprecedence_record_order— controlling records followed by exception records, highest priority first under the source-precedence rule
Domain-specific guidance
UM nurse prior-authorization review
- Check member coverage (
PT-ACTIVE):member_statusinmembersmust beactiveand the plan must be effective on the requested dates. - Check diagnosis (
PT-DX): document facts must support the lumbar/spine diagnosis. - Check functional deficit (
PT-DEFICIT): facts must include objective scores or baseline measurements. - Check plan of care (
PT-POC): POC document must be current (is_current = 1) with frequency, duration, and skilled goals. - Check unit limit (
PT-UNITS): sum of requested units across all request lines must not exceed the policy limit. - Exclude stale documents: any
documentsrow withis_current = 0goes intoexcluded_documents. - Authorization values come from
authorizationsandrequest_lines. Approved CPT codes are collected from request lines, sorted ascending by code. The modifier is the common modifier across lines (e.g.GPfor PT).
Pharmacy appeals
- Identify documented vs. undocumented failures from
drug_trials:documented = 1rows are documented failures;documented = 0rows are undocumented or insufficient. - List medications in lowercase, alphabetically.
- Check criteria:
DRUG-AUTH(member authorization),DRUG-DENIAL(denial notice),DRUG-RATIONALE(prescriber rationale),DRUG-FAILURES(formulary failures).DRUG-FAILURESispartialwhen at least one is documented but one or more required failures are missing or undocumented. required_packet_itemsinclude payer appeal items (denial notice, member authorization, prescriber rationale, formulary failure evidence) plus any assistance items (household income proof when manufacturer program is involved). Order: payer appeal items before assistance items.missing_packet_itemsare those documented as absent in the environment records. Order: appeal evidence gaps before assistance information gaps.- For
assistance, readassistance_screen. Themissing_fieldslist is sorted alphabetically by field ID. Status iseligible_readywhen all fields are present,eligible_missing_informationwhen fields are missing,not_eligiblewhen the program criteria are not met,not_applicablewhen no program applies. - Appeal deadline is the
appeal_deadlinefrom theappealstable. - Appeal path and expedited status come from the appeal record.
- Owner is the
ownerfrom the appeal record.
Payment integrity claim repricing
- Identify the stale source: look at
payment_benchmarksfor the same CPT but with aneffective_endbefore the service date (stale schedule). - Identify the current benchmark: the benchmark whose
effective_start≤ service date ≤effective_endfor matching CPT, modifier, plan type, and payer. If multiple current benchmarks exist, use the one whosesource_nameis the current commercial schedule (not a legacy export). - Compute corrected amounts:
correct_allowed_amount = allowed_amount × unitsfor each line, rounded to two decimal places. - Compute recovery:
recovery_amount = correct_allowed_amount − paid_amountfor each line. Use positive values for underpayments (correct upward). recovery_amountat the claim level iscorrect_allowed_total − paid_total.- Line disposition:
correct_upwardwhen recovery > 0,correct_downwardwhen recovery < 0,no_changewhen recovery = 0. - Sort lines by
line_numberfromclaim_lines. modifierisnull(JSON null, not string "null") when the claim line has no modifier.benchmark_sourceis thesource_nameof the current benchmark;benchmark_versionis itssource_version.stale_source_rejectedis thesource_nameof the stale benchmark, or"none"if no stale source was present.controlling_record_idsinclude the claim line IDs and the current benchmark IDs.exception_record_idsinclude stale benchmark IDs.
Peer-to-peer authorization closure
- The
p2p_outcomecomes fromp2p_events.outcome. final_statuscomes fromp2p_events.final_status(or is derived from the authorization status).new_information_changed_reviewistruewhen the P2P event supplied new patient-specific information that materially changed the original criterion result; otherwisefalse.unresolved_criterialist criterion IDs in ascending order. Only include criteria that remain unresolved after the P2P.- For the
missing_pet_factorslist, compare the P2Pnew_informationagainst the known PET-over-SPECT factors listed in the template and include every listed factor that remains unsupported. recommended_alternativeis the modality recommended when the requested service is denied (e.g.SPECT MPIwhen PET is denied).internal_appeal_deadlinecalculates 180 calendar days from the final adverse determination date (use the P2P scheduled date or the reporting date when the determination is finalized). Usenullonly when no appeal deadline applies (i.e. the result was not adverse).letter_typematches the final status:approvalfor approved,denialfor denied,partial_denialfor partially approved,no_letterwhen no letter is needed.
Therapy margin queue analysis
total_cost = variable_cost + fixed_cost_allocatedfor each row.margin = net_revenue − total_cost.revenue_to_cost_ratio = net_revenue / total_cost, rounded to 4 decimal places.below_thresholdistruewhenrevenue_to_cost_ratio < threshold_revenue_to_cost_ratio.charge_sensitivemaps directly from thecharge_sensitivecolumn (1 = true, 0 = false).recommended_action:payer_contract_reviewfor rows below threshold;monitor_charge_sensitivefor rows not below threshold but charge sensitive;monitor_no_actionfor rows with neither flag.below_threshold_segmentslists payer segments (alphabetical) that have at least one row below threshold.charge_sensitive_segmentslists payer segments (alphabetical) that have at least one charge-sensitive row not below threshold.top_issueis the segment + CPT combo for the row with the largest gap between actual revenue and 120% of cost (i.e. the most severe below-threshold issue). Format:{segment}_{cpt_code}. Use"none"when no row is below threshold.gap_to_120pct = (threshold_revenue_to_cost_ratio × total_cost) − net_revenuefor the top issue, rounded to 2 decimal places. This is the dollar gap to reach the 1.2 ratio.controlling_record_idsare all themonth_idvalues for the rows.exception_record_idsare themonth_idvalues for below-threshold rows.- Rows in the output list follow the order given in
task_context'squeue_row_ids.
Answer construction rules
- Return exactly one JSON object. No markdown fences, no surrounding prose.
- Follow every field definition in the answer template exactly: required keys, enum choices, ordering rules, and numeric precision.
- Use
nullfor absent modifiers and for dates that are explicitly inapplicable — not the string"null". - Currency values are JSON numbers rounded to two decimal places.
- Dates are ISO 8601 calendar dates (
YYYY-MM-DD). - Lists of document IDs, criterion IDs, and record IDs are sorted as specified by the answer template (ascending, alphabetical, or operational order).
- The
basis_auditis mandatory in every answer. Choose the correctsource_precedencefor the task domain, populatecontrolling_record_idswith the records that directly determine the result, andexception_record_idswith the records that explain gaps or exclusions. Orderprecedence_record_orderhighest priority first under the chosen precedence rule.