| name | payer-ops-determination |
| description | Use for Northstar-style payer-operations "structured determination" tasks: read a prompt plus task_context.json and answer_template.json, query a shared read-only payer-operations data environment (cases, members, plans, policies, criteria, documents, authorizations, appeals, drug trials, assistance screens, claims, payment benchmarks, P2P events, service-margin rows), apply the business rules, and return exactly one strict JSON object matching the template — including a basis_audit trail. Covers prior-authorization nurse determinations, pharmacy coverage appeals + manufacturer-assistance intake, claim repricing/benchmark validation, peer-to-peer (P2P) final summaries, and finance margin-queue analyses. |
Payer-Operations Structured Determination
A task in this family gives you a business target (a case / appeal / claim / queue id),
access to a shared payer-operations data environment, and a strict output contract. Your
job is to pull the relevant records, apply the operational rules, and emit one JSON object
that matches input/payloads/answer_template.json exactly.
The specific business decision differs per task, but the shape of the work is always the
same. Follow this procedure.
1. Read the three inputs before touching the environment
prompt.txt — the business ask and any special instructions (ordering, null rules,
currency rounding, date-window rules, which records to include/exclude).payloads/task_context.json — the target business id(s), the requester role, the
reporting/as-of date, environment access details, and a local_memo/finance_memo
that often states the exact rule to apply (a cost definition, a threshold, an appeal
window, a list of row ids in scope). Treat the memo as authoritative.payloads/answer_template.json — the required top-level keys, every field's type,
enum choices, ordering rule, numeric precision, date format, null convention, and
whether extra fields are allowed. This is your checklist; build to it literally.
Use the environment access details as provided in the task inputs. Access is read-only:
query records, never modify or inspect raw source/build/database files directly.
2. Discover the schema, then pull everything about the target
- Ask the environment for its table list/columns first; treat the live schema as ground
truth (see
references/data_model.md for the stable relational model and joins).
- Pull the target row, then every related row by joining on the case/claim/appeal id (and
through
member -> plan, case.policy_id -> policies -> policy_criteria, etc.).
- Pull all candidate records for the decision — including the ones you will reject.
Stale/superseded/expired/out-of-scope records are not noise; several fields explicitly
ask you to name what you excluded and why.
3. Derive each field from its authoritative source
Work field-by-field down the template. The per-family derivation rules — criteria results,
overall decision/route/letter/next-action, authorization block, evidence vs. excluded
documents, appeal routing + packet gaps + assistance, benchmark selection + line
repricing, P2P outcome + appeal-deadline math, and margin/threshold routing — are in
references/field_playbook.md. Core principles that hold across the whole family:
- Copy graded facts from the record, don't re-adjudicate. Per-criterion results,
authorization numbers/units/dates, appeal paths/deadlines/owners, benchmark amounts,
margin inputs — read them straight from the environment.
- Current beats stale. A
documents.is_current / effective-date / "most recent
applicable" flag separates the records you rely on from the ones you exclude. Relied-on
records populate the evidence/controlling lists; excluded records populate the
excluded/exception lists.
- Prefer the most specific, current match when choosing among candidate rate/benchmark
rows: match on payer + plan type + service domain + CPT + modifier, effective on the
service date. Reject expired or wrong-source rows and report which source was rejected.
- Compute derived numbers yourself, precisely, then round to the stated precision.
Cross-check that line-level numbers sum to the totals.
4. Always fill basis_audit
Every task's output includes a basis_audit object with four keys:
source_precedence — pick the one enum value describing the precedence rule this task
turned on (current-over-stale, appeal-before-assistance, effective-benchmark-by-date,
new-P2P-information, margin-threshold-then-charge-sensitivity, or
appeal-deadline-then-clinical-then-payment-integrity). Match it to the decision you made.controlling_record_ids — the environment record ids that directly drove the result
(the current evidence docs / chosen benchmark rows / the P2P event / the in-scope rows).exception_record_ids — the gap/exception/excluded records that explain an exclusion,
denial, missing information, or routing (stale exports, undocumented-failure trials, the
expired benchmark, a denial record, charge-sensitive rows). List criteria/route gaps
before stale/excluded records.precedence_record_order — the controlling and exception ids together, highest priority
first per the source_precedence rule (controlling records ahead of exceptions).
Use real ids that exist in the environment.
5. Emit and self-verify
Return JSON only — no prose, no markdown fences, nothing outside the object.
Before finishing, run the checklist in references/output_checklist.md. In particular:
match enum spellings exactly; include every required key and (when the template forbids
extras) no others; sort each list by its stated ordering rule and de-duplicate; obey each
field's numeric precision; use null (not "") for absent modifiers and null for
non-applicable dates; format dates as YYYY-MM-DD; and re-run every calculation to confirm
totals and derived values are internally consistent. You are your own reviewer — verify by
re-reading the template and re-deriving from the records, not by guessing.
