healthcare-providers-extract

What this skill does

# Healthcare Providers Extract

Structured practitioner extraction from healthcare practice websites, 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

Follow the transport selection + standard preflight from `references/nimble-playbook.md` — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

**Also simultaneously** — run WSA discovery and setup:
- `mkdir -p ~/.nimble/memory/{reports,healthcare-providers-extract/checkpoints}`
- `ls ~/.nimble/memory/healthcare-providers-extract/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-extract <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-extract only new/changed pages)
  - **Same-day repeat:** if `last_runs.healthcare-providers-extract` is today, check
    for existing report at `~/.nimble/memory/reports/healthcare-providers-extract-*[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

Parse `$ARGUMENTS` for input type using the Input Parsing Pattern from
`references/nimble-playbook.md`. Key routing:
- **URLs detected** -> proceed to Step 3
- **Specialty + location** (no URLs) -> proceed to Step 2 (practice discovery)
- **Unclear** -> ask (counts as 1 of max 2 prompts)

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

> "Extracting providers from **N practice sites**. Quick questions:
> 1. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)
> 2. Quick scan (names + credentials only) or full extraction (all 5 fields)?"

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

> **What practice sites should I extract providers from?**
> - Paste URLs directly (one per line)
> - Provide a CSV file path or Google Sheet URL with practice URLs
> - Or describe what you're looking for (e.g., "ophthalmologists in Austin, TX")
>   and I'll find practices first

Skip questions the user already answered in their initial message.

### Step 2: Practice Discovery (Optional)

Only if the user provided a specialty + location instead of URLs.

**Two input paths into discovery:**

**Path A — Fresh discovery.** User gave specialty + location. Run Layer 2 WSA
discovery for session-specific agents:

```bash
nimble agent list --limit 50 --search "[specialty]"
nimble agent list --limit 50 --search "[directory-user-mentioned]"
```

See `references/wsa-reference.md` for the full discovery strategy, agent evaluation
criteria, and healthcare discovery prioritization.

Run all discovery-phase agents simultaneously. Validate params with
`nimble agent get` first.

**Path B — Market-finder handoff.** User ran `market-finder` first and wants to
extract providers from those results. Read the market-finder output:

```bash
cat ~/.nimble/memory/market-finder/{slug}/entities.json 2>/dev/null
```

Extract practice records. Note: Google Maps results contain `place_url` (a Maps
link) but not the practice's actual website URL. Proceed to Step 2b to resolve
real website URLs before site mapping.

**After either path:** Deduplicate by domain. Present discovered practices:

> "Found **N practices** for [specialty] in [location] across [M] data sources.
> Proceeding to extract providers from these sites..."

**Fallback** — if no discovery WSAs were found, or results are sparse (< 3):
```bash
nimble search --query "[specialty] in [location]" --max-results 20 --search-depth lite
```

### Step 2b: Resolve Practice Website URLs

Discovery sources (Google Maps, Yelp, BBB) return listing URLs, not practice
website URLs. Before site mapping, resolve the actual website for each practice:

1. **Check structured data first** — Google Maps results often include a `website`
   field in the structured output. Use it if present.
2. **Extract from listing page** — if no `website` field, extract the Maps listing
   to find the practice website link:
   ```bash
   nimble extract --url "[maps-listing-url]" --format markdown
   ```
3. **Search fallback** — if extraction fails:
   ```bash
   nimble search --query "[practice-name] [city] official website" --max-results 3 --search-depth lite
   ```

Skip practices where no website URL can be resolved — note them in the "Data
Quality Summary" output section.

### Step 3: Site Mapping

Follow the Site Mapping Pattern from `references/nimble-playbook.md` for each
practice URL. Skill-specific settings:
- **Keyword weight table:** `references/provider-extraction-patterns.md`
- **Page cap:** 15 per site
- **Fallback query:** `site:[domain] doctors OR providers OR team`

For 6+ practices, use sub-agents (see Sub-Agent Strategy below).

Save checkpoint: `~/.nimble/memory/healthcare-providers-extract/checkpoints/{slug}/mapping.json`

### Step 4: Page Extraction

**WSA shortcuts first:** If WSA discovery found agents that extract provider data
from healthcare directories, use those for matching practices — structured WSA
output is higher quality than parsed markdown.

For all other practices, follow the Page Extraction with Retry pattern from
`references/nimble-playbook.md`. Scale using the Scaled Execution pattern from
the same reference.

Save checkpoint: `~/.nimble/memory/healthcare-providers-extract/checkpoints/{slug}/extraction.json`

### Step 5: Structured Parsing

Parse extracted markdown to identify providers and their fields. Read
`references/provider-extraction-patterns.md` for the 5 core fields, credential
regex patterns, and specialty keywords.

**For each extracted page:**
1. Scan for provider name patterns (Dr. prefix, heading patterns, bold text near
   credential suffixes)
2. Match credentials using the regex patterns from
   `references/provider-extraction-patterns.md`
3. Match specialty using keywords for the detected healthcare vertical
4. Extract contact info (phone regex, appointment URLs, email)
5. Extract education/training mentions

**Build structured records:**
```json
{
  "name": "Dr. Jane Smith",
  "credentials": "MD, FACS",
  "specialty": "Retinal Surgery",
  "contact": {"phone": "(555) 123-4567", "scheduling_url": "..."},
  "education": "Fellowship: Bascom Palmer Eye Institute",
  "source_url": "https://practice.com/our-doctors",
  "practice_name": "Shore Center for Eye Care",
  "practice_url": "https://practice.com",
  "confidence": "High"
}
```

### Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication and Entity Confidence Scoring patterns from
`references/nimble-playbook.md`. Skill-specific dedup rules and the 5-field
confidence criteria are in `references/provider-extraction-patterns.md`.

### Step 7: Output

Present results grouped by practice, sorted by confidence within each practice.

```markdown
# Provider Extraction: [N] Providers from [M] Practices
*[Date] | [H] High, [M] Medium, [L] Low confidence*

## TL;DR
Extracted [N] providers from [M] practice websites. [H] with comple