Northstar Payer Operations
Shared payer-operations environment for UM, appeals, payment review, and queue analysis. Every task uses the same environment and follows three stages: discover the schema, gather the evidence, and produce the determination.
Environment
Base URL from the task context. All requests need:
Authorization: Bearer pa-review-token-014
SQL endpoint (primary tool):
POST {base}/sql/query
Content-Type: application/json
{"sql": "<query>"}
Max 500 rows per query. Use SELECT * FROM {table} WHERE … to pull evidence for the target business ID.
Business REST endpoints (use when they provide a more direct path):
GET /api/tables— full schema listingGET /api/cases— all case summariesGET /api/cases/{case_id}— single caseGET /api/policies— all policiesGET /api/policies/{policy_id}— single policyGET /api/documents/{document_id}— single documentGET /api/rate-schedules— all rate schedulesGET /api/appeals— all appeal records
Workflow
Stage 1: Orient
- Read the prompt and
task_context.jsonfor the target business ID, requester role, and answer template. - Read the answer template to know every required field, enum, ordering rule, and precision constraint.
- Query
sqlite_masteror/api/tablesto confirm available tables. Read schema.md when you need column-level detail.
Stage 2: Gather Evidence
Pull every record related to the target business ID. The typical query pattern:
SELECT * FROM cases WHERE case_id = '{target}'
SELECT * FROM request_lines WHERE case_id = '{target}'
SELECT * FROM documents WHERE case_id = '{target}'
SELECT * FROM document_facts WHERE case_id = '{target}'
SELECT * FROM case_criteria WHERE case_id = '{target}'
SELECT * FROM authorizations WHERE case_id = '{target}'
SELECT * FROM members WHERE member_id = (SELECT member_id FROM cases WHERE case_id = '{target}')
SELECT * FROM policy_criteria WHERE policy_id = (SELECT policy_id FROM cases WHERE case_id = '{target}')
For workflow-specific tables, see workflows.md.
Document staleness rule: A document with is_current = 0 is stale. Stale documents must go in excluded_documents / exception_record_ids, never as controlling evidence.
Stage 3: Produce the Determination
Map criteria: Compare
case_criteriaresults anddocument_factsagainstpolicy_criteria. Each criterion ismet,not_met,unclear, ornot_applicable.Decide recommendation: Based on criteria results:
- All
met→ approve / approval letter - Any
not_metwithresult_if_missing = "deny"→ deny / adverse determination - Any
not_metorunclearwithresult_if_missing = "pend"→ pend for information
- All
Build the basis_audit:
source_precedence: Choose from the six defined rules based on the business priority at play.controlling_record_ids: Document IDs, criteria IDs, claim line IDs, or policy IDs that directly control the result. Order by operational evidence order.exception_record_ids: Stale documents, unmet criteria, missing information, or excluded records. Order: criteria/route gaps before stale/excluded records.precedence_record_order: Controlling then exception records in source-precedence order, highest priority first.
Fill the answer template exactly: Every field, every enum value, every ordering rule as the template specifies. Use
nullfor absent modifiers, not empty strings. Round currency to two decimal places. Use integer service units. Dates inYYYY-MM-DD.
Ordering Rules (recurring)
- Document IDs: ascending
- CPT codes: ascending
- Claim lines: source claim line order
- Medication names: alphabetical
- Segments (below_threshold / charge_sensitive): alphabetical by enum value
- Enum lists with fixed choices: use the order shown in choices
- basis_audit precedence: controlling then exceptions, highest priority first
- Exception records: criteria/route gaps before stale/excluded records
Enum Reference for basis_audit.source_precedence
| Value | When to Use |
|---|---|
current_clinical_records_over_stale_export |
Current documents control; stale export records are excluded |
payer_appeal_before_manufacturer_assistance |
Appeal evidence takes priority over assistance program data |
effective_benchmark_by_plan_modifier_and_date |
Benchmark selection by current effective dates, rejecting stale schedules |
new_patient_specific_p2p_information |
P2P discussion outcome plus clinical evidence; new info may change the review |
margin_threshold_then_charge_sensitivity |
Below-threshold rows control; charge-sensitive rows are secondary |
appeal_deadline_then_clinical_then_payment_integrity |
Appeal deadline priority, then clinical records, then payment data |
Detailed Workflows
For step-by-step patterns with query examples, field mappings, and computation rules for each business operation, read workflows.md. Load it when you need:
- UM prior authorization determination procedure
- Pharmacy appeals intake with manufacturer assistance screen
- Payment integrity claim repricing against benchmarks
- Peer-to-peer final determination with appeal deadline calculation
- Therapy margin queue analysis with threshold and charge sensitivity