# Healthcare Contract Risk Orchestration — Lean MVP PRD

> Generated: 2026-04-22 17:35 CST
> Source: `ScoredDemands/staffing-contract-expiry-renewal__scored-demand__20260422-1732.md`
> Score: 31/40 — BUILD
> Pipeline Run: 20260422_173231

---

## 1. Problem & User

**Target Users:** Hospital labor relations directors, healthcare HR/workforce planning leaders, hospital operations executives, and healthcare network contracting managers.

**Core Problem:** When healthcare labor or payer contracts approach renewal, negotiations stall or fail — triggering nurse strikes (e.g., BMC South 3-day strike April 30–May 3), service cuts (Valley Health trimming services citing legislation), and patient coverage loss (Premera/MultiCare standoff with June 1 deadline). Today these teams coordinate via email, spreadsheets, and ad-hoc meetings with no shared view of deadlines, open issues, staffing impact, or disruption risk. Enterprise CLM tools (Icertis, Ironclad) manage document lifecycle but don't model operational consequences. Workforce planning tools (Workday, Anaplan) handle staffing but don't connect to contract negotiation status.

**The gap:** No tool connects contract renewal status → staffing impact → disruption risk in one shared command center for healthcare teams.

## 2. Target Outcome & KPIs

- **Primary Outcome:** Hospital teams gain a shared, real-time view of contract renewal risk and staffing disruption before deadlines hit.
- **KPI-1:** Core workflow completion rate ≥ 70% (user creates contract → adds issues → views risk score within first session)
- **KPI-2:** Trial-to-paid conversion ≥ 8% within 30 days
- **KPI-3:** 7-day retention ≥ 40% (user returns to check/update at least once)

## 3. MVP Scope (In)

- Web-based dashboard for tracking labor and payer contract renewals
- Contract record creation with type (labor/payer), parties, renewal deadline, status, and owners
- Issue/milestone tracker per contract (open negotiation items, blockers, resolved items)
- Basic staffing assumption input (affected units, headcount, coverage buffers)
- Deterministic risk score engine: weighted formula based on days-to-deadline, unresolved critical issues count, staffing buffer threshold, and contract type severity
- Dashboard with countdown timers, risk heatmap (red/yellow/green), and projected disruption levels
- Email alert when risk crosses threshold or deadline is within 14/7/3 days
- CSV import for bulk contract and issue data
- Role-based access (admin, editor, viewer) via Supabase RLS
- Stripe subscription checkout ($299/mo per hospital team, up to 10 users)

## 4. Out of Scope

- AI/ML-based risk prediction or NLP contract parsing
- Native mobile apps
- Full CLM features (document versioning, e-signatures, redlining)
- Integration with Workday, ServiceNow, or existing HR systems
- SSO/SAML, SOC2 compliance suite
- Multi-language support
- Historical analytics or benchmarking across organizations

## 5. User Flow (Happy Path)

1. **Sign up** → Create organization, invite team members (up to 10)
2. **Add contract** → Enter contract name, type (labor/payer), counterparty, renewal deadline, assigned owner
3. **Add issues** → Log 3-5 open negotiation items with severity (critical/major/minor) and status (open/in-progress/resolved)
4. **Enter staffing assumptions** → Select affected units, enter current headcount, minimum coverage threshold, overtime buffer %
5. **View dashboard** → See risk score (0-100), countdown timer, disruption forecast (service lines at risk, estimated coverage gap %)
6. **Receive alert** → Email notification when risk score exceeds 70 or deadline is ≤7 days away
7. **Update & track** → Resolve issues, adjust assumptions, watch risk score adjust in real-time

## 6. Functional Requirements (P0 only)

| ID | Requirement | Notes |
|----|------------|-------|
| P0-1 | CRUD for organizations, contracts, issues, milestones, staffing assumptions | RLS via Supabase — users see only their org's data |
| P0-2 | Risk score calculation engine — deterministic weighted formula | Inputs: days_to_deadline (30%), unresolved_critical_issues (25%), staffing_buffer_gap (25%), contract_type_weight (20%) |
| P0-3 | Dashboard with contract list, per-contract risk card (score, countdown, disruption level), and org-wide heatmap | Server-rendered Next.js pages with client-side refresh |
| P0-4 | Email alerts via Resend API — triggered by daily cron job recalculating all risk scores | Thresholds: score >70, deadline ≤14d/7d/3d |
| P0-5 | CSV import for contracts and issues (drag-and-drop or file picker) | Parse with papaparse, validate schema, upsert to DB |
| P0-6 | Stripe subscription checkout — single plan $299/mo, 14-day trial | Webhook handles subscription lifecycle |
| P0-7 | Role-based access: admin (manage team + billing), editor (CRUD contracts/issues), viewer (read-only dashboard) | Implemented via Supabase RLS policies + org_members table |

## 7. Minimal Data Model

```
organizations (id, name, created_at)
org_members (id, org_id → organizations, user_id → auth.users, role: admin|editor|viewer)
contracts (id, org_id → organizations, name, type: labor|payer, counterparty, renewal_deadline, status: active|negotiating|resolved|expired, owner_user_id, created_at, updated_at)
contract_issues (id, contract_id → contracts, title, description, severity: critical|major|minor, status: open|in_progress|resolved, created_at, resolved_at)
staffing_assumptions (id, contract_id → contracts, unit_name, current_headcount, min_coverage_threshold, overtime_buffer_pct)
risk_scores (id, contract_id → contracts, score: int 0-100, disruption_level: low|medium|high|critical, calculated_at)
subscriptions (id, org_id → organizations, stripe_subscription_id, status, current_period_end)
```

## 8. API / Integration Notes

- **Auth:** Supabase Auth (email/password + magic link)
- **Database:** Supabase Postgres with RLS
- **Email:** Resend API for transactional alerts (free tier covers MVP volume)
- **Billing:** Stripe Checkout + Customer Portal + Webhooks
- **Hosting:** Vercel (Next.js) — serverless functions for cron and API routes
- **Cron:** Vercel Cron or Supabase pg_cron for daily risk recalculation at 06:00 UTC

## 9. Acceptance Criteria

- [ ] New user can sign up, create an org, add a contract with deadline, log 3 issues, enter staffing assumptions, and see a calculated risk score — all within 15 minutes
- [ ] Risk score updates within 5 seconds when an issue status changes from open → resolved
- [ ] CSV import of 50 contracts completes without error and populates dashboard
- [ ] Email alert fires correctly when risk score crosses 70 threshold (verified in Resend logs)
- [ ] Stripe checkout creates active subscription; expired subscription locks editor/admin actions but allows viewer access
- [ ] Viewer role cannot create/edit contracts or issues (returns 403)
- [ ] Dashboard loads in <2s for an org with 20 contracts

## 10. Delivery Plan

### M1 — Data Layer + Auth (Day 1 morning, ~6 hours)
- [ ] `supabase/migrations/001_schema.sql` — all tables, RLS policies, indexes
- [ ] `app/api/contracts/route.ts` — CRUD endpoints for contracts
- [ ] `app/api/issues/route.ts` — CRUD endpoints for contract issues
- [ ] `app/api/staffing/route.ts` — CRUD endpoints for staffing assumptions
- [ ] `app/api/org/route.ts` — org creation, member invite, role management
- [ ] `lib/supabase.ts` — server and client Supabase helpers
- **Exit criteria:** POST /api/contracts returns 201 with valid body; GET /api/contracts returns org-scoped list; RLS blocks cross-org access (verified with two test users)

### M2 — Risk Engine + Dashboard UI (Day 1 afternoon – Day 2 morning, ~8 hours)
- [ ] `lib/risk-engine.ts` — deterministic scoring function with weighted formula
- [ ] `app/api/risk/recalculate/route.ts` — recalculate all scores for an org
- [ ] `app/dashboard/page.tsx` — org-wide heatmap, contract cards with risk badges
- [ ] `app/contracts/[id]/page.tsx` — single contract detail with issues list, staffing inputs, risk breakdown
- [ ] `app/api/import/route.ts` — CSV import with papaparse validation
- [ ] `lib/stripe.ts` + `app/api/billing/route.ts` — Stripe Checkout session creation + webhook handler
- **Exit criteria:** Risk score for a contract with 2 critical open issues and 10 days to deadline calculates >75; dashboard renders 20 contracts in <2s; CSV import of 50 rows succeeds; Stripe test payment creates subscription record

### M3 — Alerts + Polish + Deploy (Day 2 afternoon, ~6 hours)
- [ ] `lib/alerts.ts` — email alert logic with Resend SDK
- [ ] `app/api/cron/risk-alerts/route.ts` — daily cron endpoint for risk recalculation + alert dispatch
- [ ] `vercel.json` — cron schedule configuration
- [ ] Error handling across all API routes (validation errors, auth errors, rate limits)
- [ ] `app/settings/page.tsx` — team management, billing portal link, notification preferences
- [ ] Production deploy to Vercel + Supabase production project
- **Exit criteria:** Full end-to-end flow (sign up → add contract → view risk → receive alert email) completes in <15 min; Vercel cron fires on schedule; no unhandled errors in 10-minute smoke test

## 11. Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Healthcare buyers have long procurement cycles | Slow revenue ramp | Offer 14-day free trial + monthly billing (no annual lock-in) to reduce friction |
| Risk formula too simplistic for real-world use | Users don't trust scores | Make weights user-configurable per org; show formula breakdown transparently |
| Scope creep toward full CLM features | Delays launch past 20h budget | Hard rule: any new P1+ request replaces an existing P0, never stacks |
| Email deliverability issues | Missed critical alerts | Use Resend (high deliverability) + include in-app notification badge as fallback |
| HIPAA concerns from healthcare buyers | Blocks adoption | MVP stores no PHI — only contract metadata, issue titles, and staffing numbers; document this clearly in onboarding |

## 12. Chargeability Rationale

At $299/month per hospital team, this is 10-50x cheaper than configuring ServiceNow, Workday, or Icertis for the same use case. Hospital teams already spend thousands on consultant hours coordinating contract renewals via spreadsheets. A single avoided staffing crisis (nurse strike, coverage lapse) saves tens of thousands in agency staffing costs and revenue loss. The price point is low enough for a department-level purchase (no C-suite approval needed) while high enough to sustain a focused B2B SaaS business.