healthcare-providers-enrich

What this skill does

# Healthcare Providers Enrich

Fill gaps in existing practitioner lists with verified web data, 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` ran earlier in this session by following the Sibling
Handoff pattern from `references/nimble-playbook.md`. If same-day extract output
exists, skip CLI check and profile load, and reuse WSA Layer 1/3 inventory. Only
re-run Layer 2 if the specialty 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-enrich/checkpoints}`
- `ls ~/.nimble/memory/healthcare-providers-enrich/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.

Classify discovered agents into phases 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-enrich <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-enrich only records with gaps)
  - **Same-day repeat:** if `last_runs.healthcare-providers-enrich` is today, check
    for existing report at `~/.nimble/memory/reports/healthcare-providers-enrich-*[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-extract shortcut:** Check for a same-day extract report:
```bash
ls ~/.nimble/memory/reports/healthcare-providers-extract-*$(date +%Y-%m-%d).md 2>/dev/null
```
If a same-day report exists, parse the `{slug}` from the filename and load
`~/.nimble/memory/healthcare-providers-extract/{slug}/providers.json`. The practice
domains and page URL patterns are already known — construct individual bio page URLs
from the site's URL convention and skip Step 3 entirely. This avoids N unnecessary
web searches. If no same-day report exists, do not reuse old `providers.json` files.

Parse `$ARGUMENTS` for input type using the Input Parsing Pattern from
`references/nimble-playbook.md`. Key routing:
- **Extract output detected** (providers.json) -> proceed to Step 2, mark Step 3 skip
- **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 providers** in your list. Quick questions:
> 1. Which fields need filling? (contact info, credentials, specialty, reviews, regulatory — or all gaps)
> 2. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)"

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

> **What provider list should I enrich?**
> - Paste provider data directly (name + any known info, one per line)
> - Provide a CSV file path or Google Sheet URL
> - Or describe what you have (e.g., "a list of 50 ophthalmologists with just names and states")

Skip questions the user already answered in their initial message.

### Step 2: Analyze Existing Data

Parse the input into structured records. For each provider, identify:
- **Known fields** — what the user already has (name, state, specialty, etc.)
- **Missing fields** — gaps against the 5 core fields from
  `references/provider-extraction-patterns.md` (name, credentials, specialty,
  contact, education)
- **Enrichment targets** — additional fields the user requested (reviews, regulatory,
  accreditation)

**Early exit — no gaps:** If all providers are already High confidence (5/5 fields),
skip to Step 5 (WSA enrichment) or report: "All providers already have complete
profiles. Want me to add supplementary data (reviews, clinical trials, accreditation)
instead?"

Build a gap analysis summary:

> "Analyzing **N providers**:
> - Names: N/N present
> - Credentials: N/N present (N missing)
> - Specialty: N/N present (N missing)
> - Contact info: N/N present (N missing)
> - Education: N/N present (N missing)
>
> Starting enrichment for **N providers with gaps**..."

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 "[directory-user-mentioned]"
```

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

### Step 3: Web Search for Provider Identity

For each provider with gaps, find their practice website and bio page:

```bash
nimble search --query "[provider name] [credentials] [location] [specialty]" --max-results 5 --search-depth lite
```

**Search strategy:**
- Include all known fields in the query to disambiguate common names
- Prioritize results from practice websites over directory listings
- If the provider has a known practice name, add it to the query
- For providers with only name + state, broaden: `"[name] [state] doctor"`

**Result selection:** Pick the most relevant result — practice bio page > healthcare
directory profile > LinkedIn. Save the selected URL for extraction.

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

**Checkpoint (mandatory):** You MUST write the checkpoint file before proceeding.
Interrupted runs with 20+ providers waste significant API credits without resume.
```bash
echo '{...}' > ~/.nimble/memory/healthcare-providers-enrich/checkpoints/{slug}/search.json
```

### Step 4: Extract Missing Fields

Choose extraction strategy based on provider count. Follow the Scaled Execution
pattern from `references/nimble-playbook.md` — it covers individual calls (1-10),
`extract-batch` (11-100), and the confirmation gate for larger jobs. Use the Page
Extraction with Retry pattern from the same reference for garbage detection and
retry logic.

Parse extracted content for missing fields using the detection patterns from
`references/provider-extraction-patterns.md` (credential regex, specialty keywords,
contact patterns, education mentions).

**Merge rules:**
- Only fill fields that are actually missing — never overwrite existing data
- Track which fields were added and their source URL
- If extracted data conflicts with existing data, keep the existing value and flag
  the conflict for user review

**Checkpoint (mandatory):** You MUST write the checkpoint file before proceeding.
```bash
echo '{...}' > ~/.nimble/memory/healthcare-providers-enrich/checkpoints/{slug}/extraction.json
```

### Step 5: WSA Enrichment (Optional)

If the user requested reviews, regulatory data, or accreditation — or if the gap
analysis shows most core fields are already filled and enrichment adds more value:

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

For each practice or provider, run relevant enrichment agents simultaneously.
Follow the Scaled Execution pattern from `references/nimble-playbook.md` for
batching.

**Merge enrichment data** into provider records:
- Reviews/ratings -> add as supplementary fields (not part of core 5)
- Clinical trial activ