# Dependants and the hard cases

  One adult with one card is the happy path, and no front desk needs help with it. The hard
  cases are the child with no document of their own, the patient who arrives unconscious, and
  the registry that will not answer.

Read [01 · Identify](/rail/stops/Identify) first. That page covers the step itself, meaning what
a lookup is, the identifier pair, the four moves, the three identities and what breaks. This
page only picks up what that one leaves out.

  Field names here are illustrative and still under review. Read them for the shape of the work,
  which is what you resolve and in what order. Take the exact names from
  [the Rail API reference](/rail-api/01-identify) once the contracts are signed off.

## Identifying a dependant

This is the case that catches integrations out, because a dependant often has nothing to type
into an ID field. There are two routes to them, and you need both.

<Mermaid chart={`flowchart TD
    A["A child or spouse is at the desk"] --> B{Do they have a usable identifier?}
    B -- Yes --> C["Look them up directly<br/>BIRTH_CERTIFICATE / BIRTH_NOTIFICATION / NATIONAL_ID"]
    C --> D["Resolved, on their own registry identifier"]
    B -- No --> E["Look up the PRINCIPAL instead"]
    E --> F["Read dependants[], grouped by relationship"]
    F --> G["Operator picks the dependant"]
    G --> H["Use that dependant's identifier from here on"]
    E --> I["unconfirmed_dependants[], declared but not verified"]
    I --> J["Flag for verification.<br/>Do not quietly treat as covered"]
`} />

The first route uses the dependant's own identifier. A child with a birth certificate or a
birth notification is an ordinary lookup with nothing special about it, because the type field
carries the difference.

The second route goes through the principal. Look the principal up, read `dependants[]`, and
let the operator choose. Each group carries a `relationship` and a `total`, so the screen can
render *Children (2)* and *Spouse (1)* instead of one flat list.

`unconfirmed_dependants[]` is a different thing. These have been declared but not yet verified
by the registry, and `related_to` points back at the principal. Some are legitimately pending.
They are also where fraud surfaces first. Render them separately, label them, and let the cover
check decide payability.

<Wireframe
  title="Dependants of Miriam T***"
  actor="Front desk"
  rows={[
    [
      { label: "Principal", kind: "text", span: 4, from: "principal identifier + name", note: "Always visible, because the operator needs to know whose cover this is." },
    ],
    [
      { label: "Children (2)", kind: "list", span: 4, from: "dependants[].result[]", note: "Name · date of birth · relationship · Select" },
    ],
    [
      { label: "Spouse (1)", kind: "list", span: 4, from: "dependants[].result[]" },
    ],
    [
      { label: "Declared, not yet verified (1)", kind: "field", tone: "attention", span: 4, from: "unconfirmed_dependants[]", note: "Separated and labelled on screen. Selectable, but not assumed to be covered." },
    ],
  ]}
  caption={<>Put confirmed and unconfirmed dependants in one undifferentiated list and an unverified dependant will end up billed as a covered one.</>}
/>

  Carry the principal onto the screen and onto the record. Every audit conversation about a
  dependant's claim opens with "under whose cover?", and that answer should be stored at the
  time rather than reconstructed months later.

Once resolved, a dependant is just a patient with their own identifier, carried forward like
anyone else's. The relationship matters for cover, which is
[02 · Verify cover](/rail/stops/Entitle), but it makes no difference to identity.

## The situations a front desk meets

There are six. In each one the mistake is resolving too late, resolving too often, or resolving
with too little to go on.

<CostTable
  rows={[
    {
      where: "Reception, new patient",
      symptom: "Someone presents for the first time at your facility",
      cause:
        "Look them up before you open a local file. Create the record first and resolve later, and you end up with two records for one person and no clean way to merge them.",
    },
    {
      where: "Reception, returning patient",
      symptom: "Someone you have seen before comes back",
      cause:
        "Do not re-resolve them by national ID. You stored the registry identifier the first time, so use it. This is the biggest single saving available at a busy desk.",
    },
    {
      where: "Reception, a child or spouse",
      symptom: "A dependant is presenting, often with no document of their own",
      cause:
        "Look up the person whose cover it is, then pick the dependant from their record, as above.",
    },
    {
      where: "Triage or casualty",
      symptom: "An unconscious or unidentified patient arrives",
      cause:
        "Treat first. Identity resolves on a temporary registration and is reconciled afterwards, so the lookup never blocks care.",
    },
    {
      where: "Admission",
      symptom: "An inpatient is being admitted",
      cause:
        "The identity must already be resolved. An admission opened against an unresolved patient produces a claim nobody can attach to a person.",
    },
    {
      where: "Cashier or pharmacy",
      symptom: "A bill or a dispense is being raised",
      cause:
        "Do not look up again. Carry the identifier forward from the desk. Re-resolve mid-encounter and the same patient ends up billed under two identities.",
    },
  ]}
/>

The rule underneath all six is to resolve once per patient, as early as you can, and then carry
the result.

## When the registry is slow

The registry is a national system reached over a network, and sometimes it answers more slowly
than a person standing at a desk is willing to wait. Design for that rather than treating it as
an incident.

<BuildSequence
  steps={[
    {
      do: "Choose your own timeout",
      detail:
        "Three to five seconds, set by you rather than whatever your HTTP library defaults to, which is usually far too long for someone standing at a counter.",
    },
    {
      do: "Retry once, idempotently",
      detail:
        "Reuse the same lookup reference so the attempt is de-duplicated upstream rather than recorded twice.",
    },
    {
      do: "Cap the total wait",
      detail:
        "Once you are past your budget, stop calling and change the screen. Telling the operator you will follow up beats holding them on a spinner that never ends.",
    },
    {
      do: "Offer a pending path",
      detail:
        "Let the desk carry on. Take the details, open the encounter on a temporary identity, resolve in the background and reconcile when the registry answers.",
    },
    {
      do: "Cache for life, not for a session",
      detail:
        "Most patients are returning patients, so most registry latency never reaches a user. One resolution per patient per lifetime removes most of this problem before any timeout tuning does.",
    },
  ]}
/>

<Wireframe
  title="Find patient, registry not responding"
  actor="Front desk"
  rows={[
    [
      { label: "Checking with the client registry", kind: "text", span: 3, note: "Elapsed time on screen, rather than a spinner with no end." },
      { label: "Continue anyway", kind: "action", span: 1 },
    ],
    [
      { label: "Opens the encounter on a temporary identity", kind: "field", tone: "attention", span: 4, note: "Queues the lookup and reconciles when the registry answers. Audited, and on a report until it does." },
    ],
  ]}
  caption={<>The one thing to avoid is a modal the receptionist cannot dismiss. A queue of people waiting is worse than a deferred identity.</>}
/>

  Track how many are outstanding and how long they have been open. An integration that opens
  them and never reconciles produces claims that cannot be attached to a person. That is the
  same failure as never looking anyone up, only it arrives later and is harder to trace.

## Next

Back to [01 · Identify](/rail/stops/Identify) for the step itself, or on to
[02 · Verify cover](/rail/stops/Entitle), where a resolved identity becomes a question about cover.

<AgentPrompt title="Build the hard cases with an agent" filename="identify-hard-cases.instructions.md">{`You are extending an HMIS integration with the Savannah unified payer rail.

Assumed already built: patient lookup by identifier pair (see 01 · Identify).
Task: handle dependants and the degraded paths.

DEPENDANTS (two routes, implement both):
  1. The dependant holds their own document (BIRTH_CERTIFICATE, BIRTH_NOTIFICATION,
     NATIONAL_ID): an ordinary lookup, nothing special.
  2. They hold nothing: look up the PRINCIPAL, read dependants[] (grouped by
     relationship, each group carrying a total), let the operator select, then use
     that dependant's own registry identifier from there on.
  Render unconfirmed_dependants[] as a separate, labelled group, declared but not
  verified. Selectable, never assumed covered; let the cover check decide.
  Persist the principal against the encounter: "under whose cover?" is the first
  question any audit of a dependant's claim asks.

FRONT-DESK RULES:
  - Resolve once per patient, as early as possible, then carry the identifier.
  - A returning patient is read from your own record, never re-resolved.
  - Never re-resolve mid-encounter; that is how one patient gets billed twice.
  - Casualty: treat first. Resolve on a temporary registration, reconcile after.
  - Admission requires an already-resolved identity.

SLOW OR UNAVAILABLE REGISTRY:
  - Set an explicit client timeout of 3-5 seconds.
  - Retry once reusing the same lookup reference so the attempt de-duplicates.
  - Cap the total wait; past it, change the screen rather than holding it.
  - Offer a pending path: open the encounter on a temporary identity, queue the
    lookup, reconcile on answer.
  - Track outstanding temporary identities and their age. An unreconciled temporary
    identity produces a claim that cannot be attached to a person.`}</AgentPrompt>