---
name: nhcx-insurance
description: Add the NHCX insurance plan (the payer's package master) to a hospital information system or a standalone claims desk. Request it once per facility and policy, parse both published shapes, reuse it across episodes, and quote treatment lines from it, held to the pinned bundle. Starts by checking whether the app already fetches a plan or quotes packages, and whether the coverage it depends on exists, then builds, extends or reuses only what is missing. Self-contained; needs no other skill installed. Use for the insurance plan request, the package master, package rates, quoting line items, NHCX use cases B2 and D1, flow steps F4 and F7.
---

# NHCX insurance: the package master and the lines quoted from it

This skill asks the payer for its package master on an eligible episode, flattens it into rows the desk can search, reuses a held master on later episodes, and lets the desk quote the treatment as lines priced by the plan. Every package code, rate, tier, document requirement and questionnaire the later use cases send comes from here.

Read `core/LADDER.md` first. It holds the ladder every NHCX skill walks: the definition of compliant, the stages, the workspace, how to run a stage, and the rules. This folder carries everything it needs and runs on its own; the other six NHCX skills are separate folders, and none of them has to be installed. Paths starting `core/`, `stages/`, `references/`, `fhir/`, `flow/`, `ui/`, `templates/` or `scripts/` are relative to this folder. Paths starting `nhcx-package/` are in the NHCX package, which `scripts/fetch-package.sh` fetches into the target project beside `nhcx-build/`; `references/material.md` names the package file of every pin by its label.

## What this skill covers

| | |
| --- | --- |
| Flow steps | F4 Fetch the package master, F7 Quote the treatment |
| Tabs | Insurance plan (tab 2): the master search, a package view, "All forms". Line items (tab 3): what is quoted, what goes with it, the whole master |
| Wire | `v1/insuranceplan/request`: a TaskBundle with a Task `poll` and inputs `policyNumber` and `providerId`, workflow id = the case number; `on_request` back with the InsurancePlan and Questionnaires (workflow 5 from the SHA) |
| Next actions | "Fetch the package master", "Quote the treatment" |
| Use cases | B2 Request insurance plan; D1 Fetch the insurance plan |
| Module | 7.5, whole |
| Pins | `insurance`: `nhcx-package/fhir/B2/insurance-plan-request.json` |
| Payer fixtures | `nhcx-package/fhir/C4/C4-response-pmjay.json` (package-based, PMJAY), `nhcx-package/fhir/C4/C4-response-generic.json` (coverage-based) |
| Tables | `claim_plan`, `claim_plan_benefit`, `claim_plan_form`, `claim_line`; `claim.plan_id` |
| FHIR | `fhir/FHIR.md` section 3; `references/fhir-knowledge.md` section 4 |

## Needs and hands on

Needs: an episode with a policy code, a payer code and a coverage verdict `eligible`. That is the coverage use case's work (`nhcx-coverage`); stage 0 checks for it below, whichever way the app got it.

Hands on: a plan `ready` on the episode, with benefits (rate, kind, conditions, tiers and implants, document requirements) and forms by url; quoted lines with integer quantities at the plan's rates, tiers carrying `parent_code`. Pre-authorisation builds the auth-requirements items, the Claim items, the forms and the documents from these.

## Capability check

Stage 0 (`stages/0-capability-check.md`) gives every capability below a verdict: search for the markers, run the check, record what was observed.

### Own

| Id | What | Look for | Present when (observed) |
| --- | --- | --- | --- |
| `insurance.request-builder` | `build_plan_request` | `insuranceplan/request`, `policyNumber`, `providerId`, `insurance-request-generic` | Fed the pin's data, it produces the `insurance` pin byte for byte (this bundle has no `created`) |
| `insurance.plan-parser` | `parse_plan_bundle`, both published shapes merged on package code | `InsurancePlan`, `specificCost`, `coverage[].benefit`, `Claim-SupportingInfoRequirement`, `Claim-Condition`, `stgquestionnaire` | Fed `C4-response-pmjay.json`, it yields benefits with a non-empty rate, at least one requirement with a code and a `documentationUrl`, and forms keyed by url with questions; fed `C4-response-generic.json`, it yields benefits from `coverage[].benefit[].limit[]` |
| `insurance.plan-leg` | F4: send, store, settle | a plan table with a status of `fetching`, `ready`, `empty`, `error` | With the 7.1 stub: one send on `v1/insuranceplan/request`, workflow id = the claim number, the three ids on the plan row; `C4-response-pmjay.json` applied through the door settles `ready` and replaces benefits and forms whole |
| `insurance.plan-reuse` | One plan per facility and policy | a lookup on policy code, provider id and payer before sending | A second episode on the same policy, provider and payer takes the held plan with zero sends (7.5 Validate, row 3) |
| `insurance.lines` | F7: lines from the plan | `add_line`, a line table with `parent_code` and integer quantities | A procedure line takes the plan's rate as `unit_price`; a tier carries `parent_code`; refused: a code the plan lacks, a tier the procedure does not offer, a duplicate, a zero quantity, anything before the plan is `ready` (7.5 Validate, rows 4 and 5) |
| `insurance.screens` | The Insurance plan and Line items tabs | the master search, the package view, the quoting page | Rates, tiers and requirements render from the stored plan; no rate is an input anywhere |

### Foundation

All six capabilities in `core/FOUNDATION.md`. Present when the coverage use case built them; `foundation.storage` is partial until this skill's four tables exist.

### Prerequisites

The coverage use case owns these (`nhcx-coverage`). The checks are here, so that skill need not be installed.

| Capability | Why | Look for | Present when (observed) |
| --- | --- | --- | --- |
| `coverage.episode` | The plan is keyed on the episode's policy and payer | an episode table with `claim_no`, `member_id`, `policy_code`, `payer_code` | Opening an episode from a policy row stores a unique claim number, the member id, the policy code and the payer code |
| `coverage.check-leg`, `coverage.response-reader` | F4 holds `eligible`; without a verdict there is nothing to fetch for | a send on `v1/coverageeligibility/check`; `inforce` read from `CoverageEligibilityResponse` | With a stubbed client the check sends with workflow id = the claim number; the answers in `nhcx-package/fhir/C3` applied to the episode settle it `eligible` or `not-eligible` |

### Host facts

Billing lines and the charge master (for reconciliation only, never for prices); whether a line can carry a payer package code and a category.

## The ladder, for this skill

| Stage | What is specific here |
| --- | --- |
| 0 | The tables above. |
| 1 | Confirm the shared page, or write it if this skill runs first on the app. Own rows: B2, D1. |
| 2 | Risks: one plan per facility and policy (a second request while one is open is PAYR-1406); a PMJAY master runs to tens of megabytes (56 MB seen); prices from the plan only. |
| 3 | The host facts above. |
| 4 | Confirm the homes of `claim_plan*` and `claim_line`, or write every table's home if this skill maps first. The plan request's source map; the parser's destinations; where the raw master is kept (the archive, or a column that holds tens of megabytes). |
| 5 | The Insurance plan and Line items tabs; actions F4, F7. |
| 6 | 7.5, and the foundation modules stage 0 found absent or partial. |
| 7 | 7.5, as far as its verdict says. |
| 8 | 7.5's Validate section whole. |
| 9 | The pin comparison; parser tests on both shapes; matrix rows B2 and D1, and the reuse case; the cross-cutting rows on the plan thread. |
| 10 | Rung 1. Rung 3 walks B2; rung 4 walks D1. |
| 11 | This skill's section. |

## Rules for these legs

- Prices come from the plan, never from a form and never from the HMIS charge master. `unit_price` is not editable on any screen.
- The master is keyed on policy code, provider id and payer. A facility empanelled under two policies holds two.
- Reuse before request. Ask only when nothing is held or the desk asks to refresh; a refetch replaces benefits and forms whole.
- Tiers are modifiers on the wire: a tier line carries `parent_code` and rides on its procedure's `Claim.item.modifier` when the pre-auth bundle is built.
- Questions sit on `item.prefix` more often than on `item.text`. A `/questionnaire/` url is a policy form; a `/stgquestionnaire/` url a treatment guideline.
- The validator cannot check a whole master; skip it at rung 2 and say so.

## Done when

- Every gate in this skill's block of `nhcx-build/STATE.md` is closed with evidence.
- The insurance pin passes; both parser shapes pass; the reuse case sends nothing.
- The compliance points in `core/LADDER.md` hold for F4 and F7.