Northstar Payer Operations Review
Overview
This skill covers the Northstar Health Plan payer review methodology: query a
shared API environment, evaluate cases against policy criteria and rate
schedules, and return structured JSON matching a provided output template.
The methodology applies across all Northstar review types:
- Prior authorization (UM nurse)
- Pharmacy coverage appeals and manufacturer assistance intake
- Claim repricing and payment integrity correction
- Peer-to-peer final summaries
- Therapy margin queue analysis
All tasks share a common API surface, a fixed set of source-precedence rules,
and a consistent basis-audit structure. What varies is the business domain, the
criteria keys, and the specific output fields, all of which are defined in the
per-task answer_template.json.
Environment Configuration
Every Northstar task environment exposes these endpoints:
- Base URL: provided as
<TASK_ENV_BASE_URL> in the task prompt or
environment_access.md. Resolve the placeholder to the actual URL before
making any request.
- SQL endpoint:
POST /sql/query with header
Authorization: Bearer pa-review-token-014
- Business REST endpoints:
GET / and GET /portal — system overview
GET /api/tables — available database tables
GET /api/cases and GET /api/cases/{case_id} — case records
GET /api/policies and GET /api/policies/{policy_id} — policy criteria
GET /api/documents/{document_id} — clinical and administrative documents
GET /api/rate-schedules — fee schedule and benchmark records
GET /api/appeals — appeal records
When making SQL requests, send JSON with a query field:
{"query": "SELECT ... FROM ... WHERE ..."}
The response contains a rows array or a data array with the result set.
Input File Conventions
Each task provides three files inside input/:
- prompt.txt — Business narrative: who is requesting what, and why
- payloads/task_context.json — Structured metadata: business ID, requester
role, reporting date, environment config, local memo, finance memo, queue
row IDs, and domain hints
- payloads/answer_template.json — Exact JSON output contract: required
top-level keys, field types, enum choices, ordering rules, and precision
constraints
Read all three before making any API calls. The template defines the output
shape; the context defines the business target and scope.
Workflow
Step 1: Load and Parse the Task
Read prompt.txt, task_context.json, and answer_template.json. Identify:
- The business case, appeal, claim, or queue ID (from
task_context)
- The requester role (drives the review perspective)
- The reporting date (used for effective-date comparisons and deadline math)
- Every required top-level field and its constraints
- Every allowed enum value for each field
- Every ordering rule for list fields
- Any numeric precision requirements
Step 2: Survey the Environment
Start with a broad survey to understand what data the environment holds:
GET /api/tables — discover available tables and their column names
GET /api/cases — list accessible cases; then fetch the target case with
GET /api/cases/{target_id}
GET /api/appeals — list appeal records when the task involves an appeal
GET /api/rate-schedules — list rate schedules for claim and repricing tasks
GET /api/policies — list policy and criteria records
GET /api/documents/{document_id} — fetch specific clinical or
administrative documents
Use SQL for structured extraction when REST endpoints do not expose the needed
granularity. Common patterns:
- Query a specific table with a WHERE clause on the business ID
- Join case, document, and criteria tables to correlate records
- Aggregate financial data by row ID, payer segment, or CPT code
Step 3: Gather Controlling Records
For each task type, identify which records from the environment directly control
the result and which explain gaps or exclusions:
| Task Type |
Controlling Records |
Exception Records |
| Prior auth (UM) |
Current clinical documents, authorization record |
Stale documents, unmet criteria IDs |
| Pharmacy appeal |
Appeal record, supporting trial/clinical records |
Insufficient trial records, missing packet field IDs |
| Claim repricing |
Claim lines, current benchmark/rate records |
Stale schedule records |
| P2P |
P2P event record, clinical documents |
Unmet criteria IDs, missing factor enum values |
| Margin queue |
All target service-margin rows |
Below-threshold rows, charge-sensitive rows |
For documents, separate into two categories:
- Evidence documents: current clinical or administrative records that
support the determination
- Excluded documents: stale, superseded, or irrelevant records
A record is stale when a newer record of the same type exists with a more
recent effective date or version. Cross-reference dates, versions, and
effective periods across records before deciding. Never use a stale record in
place of a current equivalent.
Step 4: Evaluate Policy Criteria
Map every criteria key from the template to data in the environment. For each
criterion:
met: the environment records clearly satisfy the criterion
not_met: the records contradict or fail to demonstrate it
unclear: the records are ambiguous or insufficient
not_applicable: the criterion does not apply to this case or task type
Check criteria against the target case's documents, member and plan context,
and applicable policy records. A criterion stays unresolved when it is
not_met or unclear and the review could not resolve it.
Step 5: Assign the Source Precedence Rule
Pick the correct source_precedence from these six rules. The task type
determines which rule applies:
| Rule |
When to Use |
current_clinical_records_over_stale_export |
Prior auth or clinical review where stale documents must be excluded in favor of current evaluation records |
payer_appeal_before_manufacturer_assistance |
Pharmacy or coverage appeal where payer-side appeal evidence takes priority over manufacturer assistance programs |
effective_benchmark_by_plan_modifier_and_date |
Claim repricing where the correct rate schedule is determined by effective date, plan, and modifier |
new_patient_specific_p2p_information |
Peer-to-peer review where the P2P discussion adds patient-specific information on top of existing clinical records |
margin_threshold_then_charge_sensitivity |
Margin queue analysis where rows are classified first by threshold violation, then by charge sensitivity |
appeal_deadline_then_clinical_then_payment_integrity |
Appeals where processing order follows deadline urgency, then clinical merit, then payment integrity |
Step 6: Construct the Basis Audit
Every output requires a basis_audit object with exactly four keys. Build them
in this order:
source_precedence: the rule selected in Step 5.
controlling_record_ids: every record ID that directly controls the
result, ordered by operational evidence priority:
- Prior auth: current clinical documents first, then authorization record
- Appeals: appeal record first, then supporting clinical or trial records
- Claims: claim lines first, then benchmark and rate records
- P2P: P2P event first, then clinical documents
- Margin: all target rows in the order they appear in the queue
exception_record_ids: records that explain gaps, exclusions, denials, or
stale data. Order criteria or route gaps before stale or excluded records
when both appear. Include:
- Stale schedule or document records that were rejected
- Unmet criteria IDs
- Missing packet items (by their field identifier from the template)
- Trial records that document insufficient or undocumented failures
- Missing PET factor enum values
A row can appear in both controlling_record_ids and
exception_record_ids when it is part of the analysis and also the record
that triggers the exception (e.g. the below-threshold row in a margin
analysis).
precedence_record_order: the full ordered trail merging controlling and
exception records in source-precedence order, highest priority first. Put
records that override or take precedence before the records they supersede.
Put controlling records before exception records of the same type. For
margin tasks, follow the queue row order from task_context.
Step 7: Fill Every Template Field
Go through the template's required top-level fields and populate each one:
- Enums: pick exactly from the allowed choices. Never invent new values.
- Lists: follow the ordering rule specified in the template. Common
orderings are: ascending by document or record ID, alphabetical by name or
code, claim-line order from the source claim, operational packet order
(payer items before assistance items), and case-specific gap order (appeal
evidence gaps before assistance information gaps).
- Numbers: match the precision in the template. Currency values are rounded
to 2 decimal places; ratios to 4 decimal places; units are whole integers.
- Nulls: use
null for absent modifiers, non-applicable dates, and
non-applicable deadline fields. Do not use empty strings.
- Booleans: return
true or false as JSON literals, not strings.
- Dates: ISO 8601
YYYY-MM-DD format.
Financial formulas to use when the template requires computed amounts:
total_cost = variable_cost + fixed_cost_allocated
margin = revenue - total_cost
revenue_to_cost_ratio = revenue / total_cost
recovery_amount (claim level) = correct_allowed_total - paid_total
recovery_amount (line level) = correct_allowed_amount - paid_amount
gap_to_120pct = (threshold x total_cost) - revenue, where threshold
is the revenue_to_cost_threshold from the task context
For internal appeal deadlines: add 180 calendar days to the adverse
determination date. If the date is not specified, use the P2P event or appeal
determination date.
Step 8: Validate and Return
Before returning, verify:
- Every required top-level key from the template is present
- Every enum value is from the allowed set
- Every list follows its ordering rule
- Every numeric value matches its precision spec
basis_audit has all four required keys
null is used for absent modifiers, not empty strings
Return exactly one JSON object. Do not wrap it in markdown fences, do not add
commentary or prose outside the JSON.
Common Pitfalls
- Mixing up stale and current records: always compare effective dates and
version identifiers. When two records serve the same purpose, the newer one
controls; the older one is an exception.
- Wrong source precedence for the task type: a prior auth uses
current_clinical_records_over_stale_export, not
effective_benchmark_by_plan_modifier_and_date. Match the rule to the task.
- Forgetting to cross-reference: the environment may hold records from
multiple tables. Join or correlate them by business ID, case ID, or document
ID before concluding.
- Using empty strings instead of null: when a modifier is absent or a
deadline does not apply, use JSON
null, not "".
- Omitting ordering rules: the template specifies list ordering for a
reason. Sorting by document ID, CPT code, or business-ID order is part of the
output contract.
- Counting stale records as evidence: a document superseded by a newer
evaluation belongs in
excluded_documents (or stale_source_rejected),
not in evidence_documents.
- Double-counting financial components: when computing
total_cost, use
the formula from the task context (variable_cost + fixed_cost_allocated),
not an ad-hoc sum.
1---2name: northstar-payer-review-23description: >4 Process Northstar Health Plan payer operations reviews that require data5 gathering from a shared API environment and structured JSON output. Use this6 skill whenever the task involves Northstar, payer operations, prior7 authorization, UM review, pharmacy appeals, claim repricing, payment8 integrity, peer-to-peer, therapy margin analysis, or any review that9 references a task environment with SQL and REST endpoints. This applies when10 the task includes a task_context.json and answer_template.json specifying the11 output contract, and mentions endpoints like POST /sql/query with a bearer12 token.13metadata:14 source: https://skillmd.com/skills/prism-shadow/northstar-payer-review-215---1617# Northstar Payer Operations Review1819## Overview2021This skill covers the Northstar Health Plan payer review methodology: query a22shared API environment, evaluate cases against policy criteria and rate23schedules, and return structured JSON matching a provided output template.24The methodology applies across all Northstar review types:2526- Prior authorization (UM nurse)27- Pharmacy coverage appeals and manufacturer assistance intake28- Claim repricing and payment integrity correction29- Peer-to-peer final summaries30- Therapy margin queue analysis3132All tasks share a common API surface, a fixed set of source-precedence rules,33and a consistent basis-audit structure. What varies is the business domain, the34criteria keys, and the specific output fields, all of which are defined in the35per-task `answer_template.json`.3637## Environment Configuration3839Every Northstar task environment exposes these endpoints:4041- Base URL: provided as `<TASK_ENV_BASE_URL>` in the task prompt or42 `environment_access.md`. Resolve the placeholder to the actual URL before43 making any request.44- SQL endpoint: `POST /sql/query` with header45 `Authorization: Bearer pa-review-token-014`46- Business REST endpoints:47 - `GET /` and `GET /portal` — system overview48 - `GET /api/tables` — available database tables49 - `GET /api/cases` and `GET /api/cases/{case_id}` — case records50 - `GET /api/policies` and `GET /api/policies/{policy_id}` — policy criteria51 - `GET /api/documents/{document_id}` — clinical and administrative documents52 - `GET /api/rate-schedules` — fee schedule and benchmark records53 - `GET /api/appeals` — appeal records5455When making SQL requests, send JSON with a `query` field:5657```json58{"query": "SELECT ... FROM ... WHERE ..."}59```6061The response contains a `rows` array or a `data` array with the result set.6263## Input File Conventions6465Each task provides three files inside `input/`:66671. **prompt.txt** — Business narrative: who is requesting what, and why682. **payloads/task_context.json** — Structured metadata: business ID, requester69 role, reporting date, environment config, local memo, finance memo, queue70 row IDs, and domain hints713. **payloads/answer_template.json** — Exact JSON output contract: required72 top-level keys, field types, enum choices, ordering rules, and precision73 constraints7475Read all three before making any API calls. The template defines the output76shape; the context defines the business target and scope.7778## Workflow7980### Step 1: Load and Parse the Task8182Read `prompt.txt`, `task_context.json`, and `answer_template.json`. Identify:8384- The business case, appeal, claim, or queue ID (from `task_context`)85- The requester role (drives the review perspective)86- The reporting date (used for effective-date comparisons and deadline math)87- Every required top-level field and its constraints88- Every allowed enum value for each field89- Every ordering rule for list fields90- Any numeric precision requirements9192### Step 2: Survey the Environment9394Start with a broad survey to understand what data the environment holds:9596- `GET /api/tables` — discover available tables and their column names97- `GET /api/cases` — list accessible cases; then fetch the target case with98 `GET /api/cases/{target_id}`99- `GET /api/appeals` — list appeal records when the task involves an appeal100- `GET /api/rate-schedules` — list rate schedules for claim and repricing tasks101- `GET /api/policies` — list policy and criteria records102- `GET /api/documents/{document_id}` — fetch specific clinical or103 administrative documents104105Use SQL for structured extraction when REST endpoints do not expose the needed106granularity. Common patterns:107108- Query a specific table with a WHERE clause on the business ID109- Join case, document, and criteria tables to correlate records110- Aggregate financial data by row ID, payer segment, or CPT code111112### Step 3: Gather Controlling Records113114For each task type, identify which records from the environment directly control115the result and which explain gaps or exclusions:116117| Task Type | Controlling Records | Exception Records |118|-----------|-------------------|-------------------|119| Prior auth (UM) | Current clinical documents, authorization record | Stale documents, unmet criteria IDs |120| Pharmacy appeal | Appeal record, supporting trial/clinical records | Insufficient trial records, missing packet field IDs |121| Claim repricing | Claim lines, current benchmark/rate records | Stale schedule records |122| P2P | P2P event record, clinical documents | Unmet criteria IDs, missing factor enum values |123| Margin queue | All target service-margin rows | Below-threshold rows, charge-sensitive rows |124125For documents, separate into two categories:126127- **Evidence documents**: current clinical or administrative records that128 support the determination129- **Excluded documents**: stale, superseded, or irrelevant records130131A record is stale when a newer record of the same type exists with a more132recent effective date or version. Cross-reference dates, versions, and133effective periods across records before deciding. Never use a stale record in134place of a current equivalent.135136### Step 4: Evaluate Policy Criteria137138Map every criteria key from the template to data in the environment. For each139criterion:140141- **`met`**: the environment records clearly satisfy the criterion142- **`not_met`**: the records contradict or fail to demonstrate it143- **`unclear`**: the records are ambiguous or insufficient144- **`not_applicable`**: the criterion does not apply to this case or task type145146Check criteria against the target case's documents, member and plan context,147and applicable policy records. A criterion stays `unresolved` when it is148`not_met` or `unclear` and the review could not resolve it.149150### Step 5: Assign the Source Precedence Rule151152Pick the correct `source_precedence` from these six rules. The task type153determines which rule applies:154155| Rule | When to Use |156|------|-------------|157| `current_clinical_records_over_stale_export` | Prior auth or clinical review where stale documents must be excluded in favor of current evaluation records |158| `payer_appeal_before_manufacturer_assistance` | Pharmacy or coverage appeal where payer-side appeal evidence takes priority over manufacturer assistance programs |159| `effective_benchmark_by_plan_modifier_and_date` | Claim repricing where the correct rate schedule is determined by effective date, plan, and modifier |160| `new_patient_specific_p2p_information` | Peer-to-peer review where the P2P discussion adds patient-specific information on top of existing clinical records |161| `margin_threshold_then_charge_sensitivity` | Margin queue analysis where rows are classified first by threshold violation, then by charge sensitivity |162| `appeal_deadline_then_clinical_then_payment_integrity` | Appeals where processing order follows deadline urgency, then clinical merit, then payment integrity |163164### Step 6: Construct the Basis Audit165166Every output requires a `basis_audit` object with exactly four keys. Build them167in this order:1681691. **source_precedence**: the rule selected in Step 5.1701712. **controlling_record_ids**: every record ID that directly controls the172 result, ordered by operational evidence priority:173 - Prior auth: current clinical documents first, then authorization record174 - Appeals: appeal record first, then supporting clinical or trial records175 - Claims: claim lines first, then benchmark and rate records176 - P2P: P2P event first, then clinical documents177 - Margin: all target rows in the order they appear in the queue1781793. **exception_record_ids**: records that explain gaps, exclusions, denials, or180 stale data. Order criteria or route gaps before stale or excluded records181 when both appear. Include:182 - Stale schedule or document records that were rejected183 - Unmet criteria IDs184 - Missing packet items (by their field identifier from the template)185 - Trial records that document insufficient or undocumented failures186 - Missing PET factor enum values187188 A row can appear in both `controlling_record_ids` and189 `exception_record_ids` when it is part of the analysis and also the record190 that triggers the exception (e.g. the below-threshold row in a margin191 analysis).1921934. **precedence_record_order**: the full ordered trail merging controlling and194 exception records in source-precedence order, highest priority first. Put195 records that override or take precedence before the records they supersede.196 Put controlling records before exception records of the same type. For197 margin tasks, follow the queue row order from `task_context`.198199### Step 7: Fill Every Template Field200201Go through the template's required top-level fields and populate each one:202203- **Enums**: pick exactly from the allowed choices. Never invent new values.204- **Lists**: follow the ordering rule specified in the template. Common205 orderings are: ascending by document or record ID, alphabetical by name or206 code, claim-line order from the source claim, operational packet order207 (payer items before assistance items), and case-specific gap order (appeal208 evidence gaps before assistance information gaps).209- **Numbers**: match the precision in the template. Currency values are rounded210 to 2 decimal places; ratios to 4 decimal places; units are whole integers.211- **Nulls**: use `null` for absent modifiers, non-applicable dates, and212 non-applicable deadline fields. Do not use empty strings.213- **Booleans**: return `true` or `false` as JSON literals, not strings.214- **Dates**: ISO 8601 `YYYY-MM-DD` format.215216Financial formulas to use when the template requires computed amounts:217218- `total_cost` = `variable_cost` + `fixed_cost_allocated`219- `margin` = `revenue` - `total_cost`220- `revenue_to_cost_ratio` = `revenue` / `total_cost`221- `recovery_amount` (claim level) = `correct_allowed_total` - `paid_total`222- `recovery_amount` (line level) = `correct_allowed_amount` - `paid_amount`223- `gap_to_120pct` = (`threshold` x `total_cost`) - `revenue`, where `threshold`224 is the `revenue_to_cost_threshold` from the task context225226For internal appeal deadlines: add 180 calendar days to the adverse227determination date. If the date is not specified, use the P2P event or appeal228determination date.229230### Step 8: Validate and Return231232Before returning, verify:233234- Every required top-level key from the template is present235- Every enum value is from the allowed set236- Every list follows its ordering rule237- Every numeric value matches its precision spec238- `basis_audit` has all four required keys239- `null` is used for absent modifiers, not empty strings240241Return exactly one JSON object. Do not wrap it in markdown fences, do not add242commentary or prose outside the JSON.243244## Common Pitfalls245246- **Mixing up stale and current records**: always compare effective dates and247 version identifiers. When two records serve the same purpose, the newer one248 controls; the older one is an exception.249- **Wrong source precedence for the task type**: a prior auth uses250 `current_clinical_records_over_stale_export`, not251 `effective_benchmark_by_plan_modifier_and_date`. Match the rule to the task.252- **Forgetting to cross-reference**: the environment may hold records from253 multiple tables. Join or correlate them by business ID, case ID, or document254 ID before concluding.255- **Using empty strings instead of null**: when a modifier is absent or a256 deadline does not apply, use JSON `null`, not `""`.257- **Omitting ordering rules**: the template specifies list ordering for a258 reason. Sorting by document ID, CPT code, or business-ID order is part of the259 output contract.260- **Counting stale records as evidence**: a document superseded by a newer261 evaluation belongs in `excluded_documents` (or `stale_source_rejected`),262 not in `evidence_documents`.263- **Double-counting financial components**: when computing `total_cost`, use264 the formula from the task context (`variable_cost` + `fixed_cost_allocated`),265 not an ad-hoc sum.