healthcare-providers-verify

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
• 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:

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:

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:

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:

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 verification status per practitioner based on the totality of evidence:

• Verified — all claims match NPI record
• Partially Verified — NPI found, minor discrepancies
• Unverified — no NPI match found or unable to disambiguate
• Flagged — active mismatches requiring human review

See references/npi-verification-patterns.md for the detailed criteria for each status and the mismatch severity levels (Critical vs Warning).

Step 5: WSA Supplementary Verification (Optional)

If the user requested regulatory verification beyond NPI lookup, or if Step 5 left practitioners as Unverified that might benefit from additional sources:

Run verification-phase WSAs discovered in Step 0. See references/wsa-reference.md for the verification phase mapping, agent evaluation, and fallback chains.

Practice confirmation: For Unverified practitioners, try confirming their practice exists via practice-level WSAs or web search:

nimble search --query "[practice-name] [city] [state]" --max-results 5 --search-depth lite

Regulatory verification: For practitioners the user wants regulatory checks on:

nimble search --query "[name] [credentials] clinical trials OR FDA OR board certification" --max-results 5 --search-depth lite

Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication pattern from references/nimble-playbook.md. Skill-specific dedup rules are in references/provider-extraction-patterns.md.

NPI dedup check: After all sub-agents return, scan for duplicate NPI numbers across batches. If two different providers mapped to the same NPI, flag both as "Flagged — possible NPI collision, requires human review." This catches data entry errors and name confusion in the source provider list.

Verification-specific scoring: The verification status (Verified / Partially Verified / Unverified / Flagged) replaces confidence scoring for this skill. Each status includes a confidence qualifier:

• High confidence — 2+ NPI sources corroborate, strong name match
• Medium confidence — single NPI source, likely name match
• Low confidence — weak name match, partial field matches

Step 7: Output

Present results as a verification report — showing status per practitioner with specific mismatch details. Group by verification status, include a "What This Means" section at the end.

# Provider Verification: [N] Practitioners Checked
*[Date] | [V] Verified, [PV] Partially Verified, [U] Unverified, [F] Flagged*

## TL;DR
Verified [V] of [T] practitioners against the NPI registry. [F] flagged for
review: [brief description of critical issues]. [U] could not be verified —
[common reason].

## Verification Results

| # | Name | Claimed | NPI Status | Verification | Issues | Source |
|---|------|---------|------------|-------------|--------|--------|
| 1 | Dr. Jane Smith | MD, Retinal Surgery, TX | Active (NPI 1234567890) | Verified | — | [NPI](url) |
| 2 | Dr. John Doe | OD, Ophthalmology, CA | Active (NPI 0987654321) | Partially Verified | Subspecialty differs | [NPI](url) |
| 3 | Dr. Alex Chen | MD, Dentistry, NY | Not Found | Unverified | No NPI match | [NPPES query](api-url) |
| 4 | Dr. Pat Lee | DO, Cardiology, FL | Deactivated | Flagged | NPI deactivated 2024-01 | [NPI](url) |

## Flagged Practitioners (Requires Human Review)

### Dr. Pat Lee
**Claimed:** DO, Cardiology, FL
**NPI Record:** NPI 1122334455 — **Deactivated** (01/15/2024)
**Issues:**
- CRITICAL: NPI status is Deactivated since January 2024
- Credential matches (DO confirmed)
- Specialty matches (Cardiovascular Disease taxonomy)
**Source:** [NPI Record](url)
**Action needed:** Confirm if provider has re-registered or if this is a
different individual.

[Repeat per flagged practitioner]

## Unverified Practitioners

[List practitioners where no NPI match was found, with search queries attempted]

## Verification Summary
- **Verified:** [V] practitioners — all claims confirmed
- **Partially Verified:** [PV] — minor discrepancies noted
- **Unverified:** [U] — no NPI match (common names, missing identifiers)
- **Flagged:** [F] — critical issues requiring review

## Sources
[Clickable URL for every NPI lookup page used, grouped by practitioner]

## What This Means
[Actionable interpretation: which practitioners are safe to include in your
directory, which need follow-up, what the verification rate tells you about
your data quality. Suggest next steps for unverified/flagged records.]

Source links are mandatory. Every verification finding must trace back to a source URL.

Step 8: Save to Memory

Make all Write calls simultaneously:

• Report -> ~/.nimble/memory/reports/healthcare-providers-verify-{slug}-{date}.md
• Verification data -> ~/.nimble/memory/healthcare-providers-verify/{slug}/verified.json
• Profile -> update last_runs.healthcare-providers-verify in ~/.nimble/business-profile.json (only if profile exists)
• Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
• Clean up checkpoint (complete run) or keep (partial run)

Update sibling artifacts: If providers.json or enriched.json exists for this slug under ~/.nimble/memory/, merge NPI numbers and verification status into those files. Generate a verified CSV export at ~/.nimble/memory/healthcare-providers-verify/{slug}/verified-{date}.csv with all verification columns (NPI, NPI Status, NPI Taxonomy, Verification Status). Offer this export path in Step 9 so the user can copy it where needed.

Step 9: Share, Distribute & Follow-ups

Always offer distribution — do not skip. Follow references/memory-and-distribution.md for connector detection and sharing flow.

Notion: full verification report as a dated subpage. Slack: TL;DR with verification counts and flagged items only.

Follow-ups:

• "Tell me more about Dr. X" -> show full verification detail
• "Export as CSV" -> generate CSV with verification statuses
• "Re-verify flagged only" -> re-run NPI search for Flagged/Unverified only
• "What should I do about the flagged ones?" -> actionable next steps per issue

Sibling skill suggestions:

Next steps:

• Run healthcare-providers-extract on unverified providers' practice URLs to get fresh data
• Run healthcare-providers-enrich to fill gaps in verified providers' records
• Run market-finder to find additional practices in this area

---

Sub-Agent Strategy

For batch verification (10+ practitioners), use nimble-researcher agents (agents/nimble-researcher.md) to parallelize NPI lookups and extraction.

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn pattern: One agent per batch of 5 practitioners. Each agent runs Steps 3-4 for its assigned practitioners and returns verification records. Tell each agent to use nimble extract-batch for its NPI result URLs where possible — one batch call per agent is faster than sequential calls.

Small batch optimization: If fewer than 10 practitioners, run directly from the main context instead of spawning agents.

Fallback: If any agent fails, run those verifications directly from the main context. Never leave gaps in the output.

---

Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

• No NPI results for practitioner: "Couldn't find an NPI record for [name] in [state]. The name may be too common, or the provider may practice under a different name. Want me to try with additional context (practice name, NPI number)?"
• Multiple NPI matches: "Found multiple NPI records for [name] in [state]. Can you confirm which one? [list top 3 with NPI numbers and specialties]"
• NPI page extraction returned garbage: "The NPI lookup page appears to be JavaScript-rendered. Retrying with browser rendering..." (auto-retry with --render per the shared pattern)
• CSV/Sheet parse error: "Couldn't parse the input file. Expected columns with practitioner names and at least one identifier (state, specialty, or credentials). Can you paste the data directly instead?"
• Insufficient data for verification: "Cannot verify [N] practitioners — they have only a name with no state, credential, or specialty. Add identifiers or remove them from the list."