Doctor + Rx session prompt — research-first, discuss-before-build

Paste this verbatim into a fresh Claude Code session opened in /Users/tahaabbasi/Developer/ask-florence-doctor-rx/.

You're picking up the Doctor + Drug coverage feature for AskFlorence. AskFlorence shows Americans the real subsidized price of ACA health insurance plans. Today the platform answers "what's my real price?" but it can't yet answer the immediate next question every user has: "Is my doctor in this plan? Are my prescriptions covered?" Phase C (drug formulary) and Phase D (provider directory) close that gap.

This first session is research, not build. I want you to investigate the data landscape, propose an approach, and discuss it with me BEFORE writing ingest code or UI. Don't ship anything in this session except a research document.

Step 0 — sync from main first

This worktree was forked from main at v0.34.0. Since then main has shipped v0.35.0 which includes the design system, brand guide, and /plans design brief. Sync first:

bash

git fetch origin main
git merge origin/main

Confirm docs/design-system.md, docs/briefs/plans-redesign-brief.md, src/app/design-system/, and src/app/brand-guide/ are present after merge.

Step 1 — required reading (before any investigation)

docs/briefs/plans-redesign-brief.md §7 (Component spec) — RxLookupSheet and ProviderLookupSheet are listed as Phase C/D deliverables. Skim the full brief for context on how /plans will eventually surface these features.
scripts/db/ingest-puf-augment.js — read end-to-end. This is how we ingested plan data from the CMS PUF (Plan and Network) files into MongoDB. Pay special attention to lines mentioning networkId and formularyId. Those foreign keys are already in the puf.* namespace on every plan document.
src/lib/owned-plans.ts — see how plan data flows from MongoDB → Plan shape → UI. We do NOT call CMS API at runtime for plan data. The model for Phase C/D should mirror this: ingest once, query MongoDB at runtime.
CLAUDE.md — read the "Compliance-first architecture" section. Drug + provider data is PHI-adjacent. Decisions on logging, vendor BAAs, audit trails matter from day one.

Step 2 — the investigation (this session's actual work)

Spend most of this session on these probes. Output is a research document, NOT code.

2a. What CMS provides at runtime (probe)

CMS has multiple data sources for provider + drug coverage. Validate each:

CMS Marketplace API (developer.cms.gov/marketplace-api) — does it expose provider lookup endpoints? Drug coverage endpoints? What's rate-limited? Latency?
NPPES (National Plan & Provider Enumeration System) — federal NPI registry. What does it give us about doctors? Specialty, address, accepted plans?
Healthcare.gov provider lookup — when you click a plan there, where does the data actually come from? Is it a CMS-provided service or per-issuer?
Per-issuer formulary URLs — puf.urls.formulary is in our MongoDB. Pull a few real values (Select Health, Cigna, Anthem) and see what those URLs actually return. PDF? HTML? JSON? Do they require authentication?
Per-issuer provider directory URLs — same probe for puf.urls.providerDirectory if it exists.

For each source, document:

What it provides
Latency / rate limits
Cost (free, $/call, vendor)
HIPAA BAA status
Data freshness (is it stale?)

2b. What we already have ingested (audit)

Connect to our MongoDB (read-only, use MONGODB_URI) and inspect:

Pick 5 plans across 3 issuers. What's actually in puf.networkId, puf.formularyId, puf.urls.* for each?
Is the data consistent? Sparse? Some plans might have these fields, others null.
Are there other related fields we ingested (puf.networks, puf.benefitDetails, puf.formularies) that we forgot we have?

2c. What competitors do

Healthcare.gov — when you check "Find a doctor" / "Check your prescriptions" on their plan finder, where does the data come from? Try it for a real Salt Lake County plan and inspect the network requests.
CoveredCA — same probe.
Vendor landscape — quick search: who sells provider-directory APIs to ACA platforms? Names like Trizetto, Availity, Change Healthcare. Drug formularies: First Databank, Medispan. Cost ballparks if findable.

2d. Compliance lens

This data is PHI-adjacent. Logging "user X searched for Lipitor + Dr. Smith" crosses into PHI territory.

What can we log without HIPAA-tier analytics?
What does the existing PostHog setup permit?
See CLAUDE.md "Compliance-first architecture" — agent_audit_log is Phase 5; until that ships, what's our boundary?
For vendor selection, BAA coverage is required (see #57).

Step 3 — output of this session

A markdown research document at:

docs/briefs/doctor-rx-research.md

Sections:

Executive summary — recommended approach in 5 bullets.
Data landscape — what each source provides, with concrete examples (real API responses, real PDF excerpts).
Build vs buy — should we ingest into our own MongoDB collection (like we did for plans) OR call vendor APIs at runtime? Trade-offs for each. Recommendation.
Coverage probe — for one issuer (recommend Select Health, well-covered), can we crawl their formulary + directory URLs reliably? Sample data + parse difficulty.
MongoDB shape proposal — if we go ingest-route, how would formularies and providers collections look? Sharding key, document shape, index strategy.
API surface proposal — what endpoints /api/formulary/search, /api/providers/search look like.
UI hook-points (already designed) — pointer to the /plans brief Wave 4/5 integration.
Compliance + privacy — vendor BAA requirements, logging boundaries, what we audit.
Open questions — decisions that need Taha + Asad input (vendor pick, crawl ToS, BAA negotiations).

Step 4 — discuss with me before any code

Once the research doc is drafted, stop. Ping me with:

The recommended approach (build vs buy, ingest vs runtime).
The biggest open question.
Estimated build effort for the recommended path.

We discuss. Then if approved, you start Phase C ingest work in a follow-up session. Do not write ingest scripts or UI code in this session.

Hard constraints (carry through to follow-up sessions)

Editorial register when UI eventually ships: cream paper bg, ink text, gold-italic accents on emotional copy, Outfit prices. See docs/design-system.md and the /design-system page (visit at dev npm run dev).
No round pills — 4px radius (rule resolved in v0.35.0).
WCAG AA on all text combinations — see docs/design-system.md §9.
All interactive elements ship full state set — see docs/design-system.md §11.
No em dashes or en dashes in any user-facing copy.
Don't modify src/lib/owned-plans.ts, src/lib/fetch-plans.ts, src/lib/csr.ts, src/lib/types.ts, src/lib/hooks/use-calculator.ts, or any /api/* route. Pricing/data layer is audit-locked.
Use class prefix af-l2-rx__* for Phase C and af-l2-net__* for Phase D when UI ships.

Branch + version + deploy discipline

Work on the doctor-rx-flow branch in this worktree.
Never push to main. When a coherent ship is ready, open a PR.
NEVER bump package.json version inside this worktree. Version bumps require explicit Taha approval and are batched with deploy moments. Worktree PRs land on main without touching the version. See CLAUDE.md "Deploy + release cadence policy" for the full rule.
Don't add CLAUDE.md "What shipped" entries inside this worktree either. Draft them in the PR description; Taha appends to CLAUDE.md on main at version-bump time.
Don't deploy anything. That's Taha's call after merge per the cadence policy (1-2 deploys/day max, end-of-day, explicit "ship it" only).
If main advances while you work, periodically git fetch origin main && git merge origin/main to stay current.

Start here

Sync from main, read the brief + design system + ingest script, then start the investigation. Output is docs/briefs/doctor-rx-research.md plus a discussion ping. No code this session.