---
name: nhcx-coverage
description: Add NHCX policy search and coverage eligibility (discovery, validation, benefits) to a hospital information system, or build it into a standalone claims desk, held byte for byte to the pinned bundles. Starts by checking whether the app already searches policies and checks cover, then builds, extends or reuses only what is missing. Self-contained; needs no other skill installed. Use for policy search, coverage eligibility checks, "is this patient covered", NHCX use cases A2, B1 and D3, flow steps F1 to F3.
---

# NHCX coverage: policy search and coverage eligibility

This skill finds a beneficiary's policy, opens the claim episode on it, and asks the payer whether the cover is in force. It is the first of the seven NHCX use cases in episode order: the others start from the episode and the verdict it leaves.

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 | F1 Policy search, F2 Open the case, F3 Check the cover (`flow/FLOW.md`) |
| Screens and tabs | The "New case" screen; the Eligibility tab (tab 1) with the beneficiary and verdict cards |
| Wire | The participant service's `participant/get/policies` (plain REST, through the transport); `v1/coverageeligibility/check`, purpose `discovery`, `validation` or `benefits`, workflow id = the case number, a new correlation id per check; `on_check` back |
| Next actions | "Check the cover" |
| Use cases | A2 Get policy; B1 and D3 Check coverage eligibility |
| Module | 7.4, whole (`stages/7-write-code/7.4-policy-and-coverage.md`) |
| Pins | `coverage/discovery`, `coverage/validation`, `coverage/benefits`: `nhcx-package/fhir/B1/{discovery,validation,benefits}.json` |
| Payer fixtures | `nhcx-package/fhir/C3/*`: the validation, discovery and benefits answers, generic and PMJAY |
| Tables | `claim`, the episode, with its coverage columns |
| FHIR | `fhir/FHIR.md` section 2; `references/fhir-knowledge.md` section 3 |

Not here: the `auth-requirements` purpose. It uses this skill's builder with items and belongs to `nhcx-preauth` (F8).

## Needs and hands on

Needs from other use cases: nothing. This skill runs first.

Hands on: an episode (`claim` row) with a claim number, member id, policy code, the payer's and the processor's participant codes, and the raw policy; a verdict `eligible` or `not-eligible` with the payer's demographics, wallet and period. Insurance and pre-authorisation start from an `eligible` episode. Pre-authorisation reuses the coverage builder for auth requirements, so keep it a pure function that takes `items`.

## 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) |
| --- | --- | --- | --- |
| `coverage.policy-search` | F1: search by `AbhaNumber`, then `MemberId`, then `MobileNo`, and normalise each policy | `participant/get/policies`, `identifiertype`, `processingid`, `AbhaNumber`, `MobileNo`, `NHCX-1016` | Called with a stubbed answer, it returns rows with `member_id` (`memberid`), `policy_code` (`productid`), `payer_code` (`payerid`) and `recipient_code` (`processingid`); a policy with no `processingid` is refused as unaddressable; an NHCX-1016 answer is an empty list, not an error |
| `coverage.episode` | F2: open the case on a chosen policy | an episode table with `member_id`, `policy_code`, `payer_code`, `recipient_code`; a claim number generator | Opening from a policy row stores the member id, policy code, payer code, recipient code and the raw policy, mints a unique claim number and stamps `eligibility / draft` |
| `coverage.request-builder` | `build_coverage_request`, a pure function | `CoverageEligibilityRequest`, `coverageeligibility`, `"purpose"`, `"NONE"` | Fed each pin's own data, it produces the `discovery`, `validation` and `benefits` pins byte for byte in canonical JSON, `created` excluded; every reference resolves; the Patient carries only the two identifiers (7.4 Validate, rows 1 to 4) |
| `coverage.response-reader` | Read `on_check` and settle the verdict | `CoverageEligibilityResponse`, `inforce`, `allowedMoney`, `usedMoney`, `disposition` | Fed every answer in `nhcx-package/fhir/C3`, it yields `inforce`, `outcome` and a non-empty patient name, and settles `eligible` or `not-eligible` (7.4 Validate, rows 5 and 6) |
| `coverage.check-leg` | F3: send the check and keep its thread | a send on `v1/coverageeligibility/check`; `txn_id`, `correlation_id`, `api_call_id` on the episode | With the 7.1 stub: one send, workflow id equal to the claim number, the three ids stored, status `checking`; a ProtocolResponse, or a 404 on `txn/related`, settles `error` and never spins |
| `coverage.screens` | The New case screen and the Eligibility tab | a route like `/claims/new`; the verdict card | On a seeded answer the tab shows sum insured, utilised, wallet balance, disposition verbatim, in force, pre-authorisation required, checked at and correlation, all rendered from the stored answer and none of them an input |

### Foundation

All six capabilities in `core/FOUNDATION.md`; `foundation.shell` only in standalone mode. As the first use case, this skill usually finds the foundation absent and builds it.

### Prerequisites

None.

### Host facts

The stage 3 rows this skill needs: framework and runtime; configuration; inbound route and middleware; background worker; screen conventions; test runner; patient table and key; name, gender, date of birth, phone, ABHA; where a member id and policy code can be stored; facility HFR id, name and participant code.

## The ladder, for this skill

| Stage | What is specific here |
| --- | --- |
| 0 | The tables above. |
| 1 | Usually the first skill: write `1-idea.md` whole, every step of the flow with its skill, and ask the user. Own rows: A2, B1, D3. |
| 2 | Risks: validate then discover on a fresh episode (the sandbox's order); the workflow id is the case number, not a code; demographics are the payer's to return; and the foundation rules when the foundation is built here. |
| 3 | The host facts above. |
| 4 | Usually first: the flow table and every table's home. Then the coverage bundle's source map and the `on_check` destinations. Only the member id goes out; the payer returns the rest. |
| 5 | Usually first: the case screen shell. Then the New case screen and the Eligibility tab: values, empty states, actions F1, F2, F3. |
| 6 | 7.4, and every foundation module stage 0 found absent or partial. |
| 7 | The foundation first, then 7.4, each only as far as its verdict says. |
| 8 | 7.4's Validate section whole; the Validate section of every foundation module built or extended here. |
| 9 | Three pin comparisons; a reader test per coverage fixture; matrix rows B1 and D3; the cross-cutting rows on the coverage thread. |
| 10 | Rung 1. The rung 3 driver walks B1 against a generic payer; rung 4 walks D3. |
| 11 | This skill's section. |

## Rules for these legs

- Validate, then discover, on a fresh episode; a `benefits` check is optional.
- The workflow id on these legs is the case number.
- The request carries identifiers only: the Patient has the member id typed `PMJAY` and `MB`, and no name. The payer's demographics come back on the answer and are stored on the episode, not written into the HMIS patient unless stage 4 said so.
- `Coverage.identifier` is `NONE` on discovery and the policy code otherwise.
- The policy search answer's shape is not published. Read a real one first and keep the raw JSON on the episode.
- "Check again" is allowed from any settled state.

## Done when

- Every gate in this skill's block of `nhcx-build/STATE.md` is closed with evidence, and every foundation row this skill built is closed.
- The three coverage pins pass their comparisons.
- The compliance points in `core/LADDER.md` hold for F1 to F3.