healthcare-providers-verify

What this skill does

# Healthcare Providers Verify

Validate practitioner credentials against the NPI registry and authoritative
sources, powered by Nimble's web data APIs.

User request: $ARGUMENTS

**Before running any commands**, read `references/nimble-playbook.md` for Claude Code
constraints (no shell state, no `&`/`wait`, sub-agent permissions, communication style).

---

## Instructions

### Step 0: Preflight + WSA Discovery

**Sibling handoff check:** Before running full preflight, check if
`healthcare-providers-extract` or `healthcare-providers-enrich` ran earlier in this
session by following the Sibling Handoff pattern from `references/nimble-playbook.md`.
If same-day output exists, skip CLI check and profile load, and reuse WSA Layer 1/3
inventory. Only re-run Layer 2 if the verification focus changed.

**Otherwise, run full preflight** from `references/nimble-playbook.md` (5 simultaneous
Bash calls: date calc, today, CLI check, profile load, index.md load).

**Also simultaneously** — run WSA discovery and setup:
- `mkdir -p ~/.nimble/memory/{reports,healthcare-providers-verify/checkpoints}`
- `ls ~/.nimble/memory/healthcare-providers-verify/checkpoints/ 2>/dev/null`
- Run Layer 1 (vertical) and Layer 3 (general tools) WSA discovery from
  `references/wsa-reference.md`. Layer 2 (session-specific) runs after Step 1 when
  you know the user's specialty and verification focus.

Classify discovered agents into verification categories and validate with
`nimble agent get` per `references/wsa-reference.md`.

From the preflight results:
- CLI missing or API key unset -> `references/profile-and-onboarding.md`, stop
- Tag all `nimble` CLI calls: `nimble --client-source skill-healthcare-providers-verify <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists -> note it for context. Determine mode using smart date windowing
  from `references/nimble-playbook.md`:
  - **Full mode:** first run OR last run > 14 days ago
  - **Quick refresh:** last run < 14 days ago (re-verify only previously
    Unverified/Flagged practitioners)
  - **Same-day repeat:** if `last_runs.healthcare-providers-verify` is today, check
    for existing report at `~/.nimble/memory/reports/healthcare-providers-verify-*[today].md`.
    If found, ask: "Already ran today. Run again for fresh data?"
- No profile -> that's fine. This skill doesn't require onboarding. Proceed to Step 1.

### Step 1: Parse Input + Starting Questions

**Chained-from-sibling shortcut:** Check for same-day extract or enrich output:
```bash
ls ~/.nimble/memory/reports/healthcare-providers-extract-*$(date +%Y-%m-%d).md 2>/dev/null
ls ~/.nimble/memory/reports/healthcare-providers-enrich-*$(date +%Y-%m-%d).md 2>/dev/null
```
If a same-day report exists, parse the `{slug}` and load the provider data
(`providers.json` or `enriched.json`). This gives you names, credentials, specialties,
and locations — skip parsing and go directly to Step 2.

Parse `$ARGUMENTS` for input type using the Input Parsing Pattern from
`references/nimble-playbook.md`. Key routing:
- **Sibling output detected** (providers.json/enriched.json) -> proceed to Step 2
- **CSV/Sheet/pasted data detected** -> proceed to Step 2
- **Unclear** -> ask (counts as 1 of max 2 prompts)

**If input is clear**, confirm and ask one shaping question (plain text, not
AskUserQuestion):

> "Found **N practitioners** to verify. Quick questions:
> 1. What should I verify? (credentials, specialty, active status, practice address — or all)
> 2. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)"

**If input is ambiguous**, use AskUserQuestion (counts as 1 of max 2 prompts):

> **What practitioner data should I verify?**
> - Paste provider data directly (name + credentials + location, one per line)
> - Provide a CSV file path or Google Sheet URL
> - Or describe what you have (e.g., "a list of 50 ophthalmologists I need to
>   verify against the NPI registry")

Skip questions the user already answered in their initial message.

### Step 2: Analyze Input Data

Parse the input into structured records. For each practitioner, identify:
- **Claimed fields** — name, credentials, specialty, state/city, practice name
- **Verification targets** — which claims to check based on user's focus

**Minimum required fields:** Name + at least one of (credentials, state, specialty).
If a practitioner has only a name with no other identifiers, flag it:
"Cannot verify [name] — need at least a state, credential, or specialty to search."

Build a verification plan summary:

> "Analyzing **N practitioners** for verification:
> - Names: N/N present
> - Credentials claimed: N/N
> - Specialty claimed: N/N
> - State/location: N/N
>
> Starting NPI verification..."

Run Layer 2 WSA discovery now that you know the specialty:
```bash
nimble agent list --limit 50 --search "[specialty]"
nimble agent list --limit 50 --search "[registry-user-mentioned]"
```

See `references/wsa-reference.md` for session-specific discovery.

### Step 3: NPI Registry Lookup

**Prefer the NPPES API** — it returns structured JSON in one call instead of
search + extract (two calls). Build the query URL from the practitioner's fields:

```bash
nimble extract --url "https://npiregistry.cms.hhs.gov/api/?version=2.1&first_name=[First]&last_name=[Last]&state=[ST]&limit=5" --format markdown
```

Add `&taxonomy_description=[Specialty]` if the specialty is known and specific
enough. The API returns NPI number, status, credentials, taxonomy codes, addresses,
and enumeration dates — everything needed for verification in a single call.

**Fallback to web search** if the NPPES API returns zero results or errors:

```bash
nimble search --query "[Name] [Credential] [State] NPI registry" --max-results 5 --search-depth lite
```

Then extract the top result from an NPI source (see source priority below).

**Source priority (enforce in sub-agent prompts):**
1. NPPES API (`npiregistry.cms.hhs.gov/api/`) — preferred, structured JSON
2. `npidb.org/doctors/` — clean structured data, good fallback
3. `nppes.cms.hhs.gov` (provider-view pages) — official CMS source
4. Skip all others (healthline, hmedata, vitals, etc.) — inconsistent formatting

Tell sub-agents: "Only extract from NPPES API, npidb.org, or nppes.cms.hhs.gov.
Ignore other NPI aggregator sites."

**Search budget per provider:** Max 3 search queries + 1 extraction per
practitioner. If no NPI match after 3 attempts, mark as Unverified and move on.
Tell sub-agents: "Do not run more than 4 nimble commands per provider. Mark as
Unverified if no match by then."

For 10+ practitioners, use sub-agents (see Sub-Agent Strategy below).

**Key fields from NPI records** — see `references/npi-verification-patterns.md`
for the full list: NPI number, status, credentials, taxonomy/specialty,
enumeration date, last updated, practice address.

**Checkpoint enforcement:** After each sub-agent returns its batch results, the
main context MUST write the checkpoint before spawning the next step or presenting
results:
1. Receive sub-agent results
2. Write checkpoint: `echo '[results]' > ~/.nimble/memory/healthcare-providers-verify/checkpoints/{slug}/batch-{n}.json`
3. Continue to next step

Do NOT skip this — if the run fails between steps, the user loses all progress.

### Step 4: Cross-Reference and Verify

For each practitioner, compare claimed data against extracted NPI data. Follow the
verification logic in `references/npi-verification-patterns.md`:

1. **Name matching** — normalize both names and determine match level (Strong,
   Likely, Weak, No Match) per the name matching rules in the reference
2. **Credential matching** — compare claimed credentials against NPI record
3. **Specialty matching** — compare claimed specialty against NPI taxonomy using
   the taxonomy matching strategy in the reference
4. **Address matching** — compare claimed state/city against NPI practice address
5. **Status check** — verify NPI status is Active

**Assign