# Signal Demo MVP — Design Spec
**Date:** 2026-06-07  
**Goal:** Demo-ready Signal for Robert Robinson (Gaboro) on Tuesday June 10, 2026  
**Deadline:** Monday June 9 EOD (one day buffer before meeting)  
**Approved by:** Kisa Fenn  
**Build session:** Next session — dangerously-skip-permissions, Max plan

---

## What We Are Building

A polished, demo-ready Signal that tells a compelling story to Robert Robinson on Tuesday. He has never seen Signal. His biggest documented pain is the 6-month qualifying visit requirement. The demo runs on synthetic PA/NJ patient data, shows the full documentation state machine, includes one live Confirm Visit interaction, and leaves Robert with a pilot LOI and NDA to review.

This is Option 2 (Polish + Confirm Visit Workflow). Not building: column mapping review UI, Brightree/NikoHealth API, or any Phase 2/3 tabled items.

---

## Section 1: Visit Date Workflow and Priority System

### Visit Date Priority Chain

Signal determines a patient's qualifying visit date in this order:

1. A column explicitly labeled as a visit or encounter date in the current CSV import
2. A previously confirmed visit date stored in Supabase for that patient_id (entered by staff via Confirm Visit in a prior session)
3. Estimated proxy: shipment_date minus 30 days, labeled clearly as "Estimated — verify with prescriber office"

Priority 1 and 2 display as "Confirmed." Priority 3 displays as "Estimated" in amber with verification note.

### Validation Rule

A qualifying visit date is valid only if it falls within 6 months before the order/shipment date for the current supply cycle. A date older than 6 months from the order date is flagged as expired and the patient moves to Visit Required status.

### Proactive Priority System: 90/60/45 Days

Signal calculates `Next_Visit_Due = Last_Confirmed_Visit_Date + 6 months` for every patient. Days remaining determines priority tier:

| Days to Next Visit | Status Label | Visual |
|---|---|---|
| > 90 days | Active | Green, normal weight |
| 90 days | Renewal Due SOON | Amber, normal weight |
| 60 days | Renewal Due SOON | Amber, **bold** |
| 45 days or less | Renewal Due — Critical | **Red, bold** + supplier outreach flag |
| Past due, no new visit | Visit Required | **Red, bold** + warning icon |
| Past due, supplies run out | Supply Lapsed | Dark red, bold + alert banner, top of list |

At 45 days: Signal adds a staff action flag — "Contact prescriber office — confirm patient appointment is scheduled for qualifying visit." Signal is never responsible for patient outreach, now or in any future phase. The prescriber is the right contact because they have a fax number already on file from the SWO, they control the appointment calendar, and they are the authoritative source for scheduling the qualifying visit. Phase 2 may include a Signal-facilitated fax to the prescriber's office with a pre-filled renewal reminder. Patient contact remains the supplier's responsibility outside of Signal.

Worklist sorts by urgency: Supply Lapsed → Visit Required → Renewal Due Critical → Renewal Due Elevated (60d) → Renewal Due SOON (90d) → Active.

### Confirm Visit Interaction

Each worklist row shows a "Confirm Visit" button when visit status is Estimated or Not Confirmed.

Modal contains:
- Label: "Qualifying visit date — confirmed with prescriber office or from SWO on file"
- One date input field
- Validation: must be within 6 months of order date, cannot be future date
- Helper text: "Contact prescriber office to confirm. Do not use patient-reported date."

On save: Signal stores confirmed date in Supabase against patient_id, immediately recalculates Next_Visit_Due, updates row status and priority tier live (no page refresh). Confirmed date persists across all future imports for that patient_id.

---

## Section 2: Full Documentation State Machine

Each patient tracks five documentation items. Requirements vary by payer type.

### Documentation Items

- **SWO (Standing Written Order):** On File / Pending / Expired
- **Qualifying Visit:** Confirmed [date] / Estimated [date] / Not Confirmed
- **PECOS Enrollment:** Verified / Not Verified (Medicare patients only)
- **Prior Authorization:** Not Required / Approved [exp date] / Pending / Denied / Required — Not Started
- **Diagnosis:** On File / Missing

### Payer-Dependent Requirements

**Traditional Medicare (Part B FFS):** SWO, Qualifying Visit, PECOS, Diagnosis. PA marked "Not Required" (CGM coverage expansion 2023; PA exemption via CMS-1828-F for ≥90% affirmation rate suppliers).

**Medicare Advantage:** SWO, Qualifying Visit, PECOS, Diagnosis, PA — all required. PA varies by plan per payer_rules.json.

**Medicaid (PA and NJ):** SWO, Qualifying Visit, Diagnosis, PA. PECOS not required. State-specific PA rules via payer_rules.json.

**Commercial:** SWO, Qualifying Visit, Diagnosis, PA (plan-dependent). PECOS not required.

### Cascade Display

When a documentation item is missing, Signal shows the downstream consequence inline on the expanded patient row:

> "Qualifying visit not confirmed → SWO validity at risk → PA renewal cannot proceed → next shipment blocked"

This cascade is visible on the expanded row, not buried in a detail screen.

### Worklist Row UI

Compact documentation status bar (5 dots, one per item, colored by status). Expanding a row shows the full checklist with labels and recommended actions for each missing or at-risk item.

---

## Section 3: Cycle Reset via CSV Re-Import (No Manual Entry)

### Design Principle

Gaboro already exports from Brightree on a regular cadence. Signal leverages that existing workflow. No staff entry required to update supply cycle status.

### How It Works

When Gaboro uploads a new CSV, Signal compares it to the previous import for each patient_id:

- New shipment date detected → Signal automatically advances the patient's supply cycle clock
- New visit date column detected with a valid date → Signal updates confirmed visit date
- Patient appears with updated payer → Signal rechecks PA requirements per payer_rules.json
- Patient disappears from import → Signal flags for review (discharged? transferred?)

Signal maintains a per-patient import history in Supabase (timestamp, shipment date, detected documentation status). Each import creates a snapshot record for diff comparison.

### Phase 2 Path

Brightree/NikoHealth API integration makes this real-time. Signal's data model is designed for this from day one — the import-based diff logic is identical to what the API would trigger.

---

## Section 4: Transferred Patients

### Problem

When a patient transfers from another DMEPOS supplier to Gaboro, Gaboro has no history: no SWO, no qualifying visit date, no PA history. The patient may be established on CGM (active user, mid-cycle) or new to CGM entirely.

### Signal Handling

Signal detects a transferred patient when:
- A patient_id appears for the first time with a shipment date that predates their first import (gap in history)
- A column labeled "Transfer_From", "Previous Supplier", "Transfer Status", or similar is present
- A patient_id appears with a very old shipment date but no prior import history

Status assigned immediately: **"Needs Verification — Transfer Patient"**

Worklist displays: "Patient transferred from prior supplier. Verify: SWO from current prescriber, qualifying visit within 6 months, PA status with current payer."

All five documentation items default to "Pending — Verify" for transferred patients. Staff must confirm each item before Signal clears the patient to Active.

### CSV Accommodation

The challenge CSV sets include transferred patient scenarios: patients with Transfer_From columns, patients with history gaps, and patients who are new to CGM vs. established users mid-cycle.

---

## Section 5: CSV Test Suite

### Overview

Two new sets of 25 CSV files each (50 total), plus the existing 25-file set remains as baseline. Both new sets are stress-test level with state-change patients, transferred patients, and all challenge types.

Existing generator (generate_samples.py) is the reference framework. Two new generators extend it: generate_pa_set.py and generate_nj_set.py.

### Automated CSV Generator — Parameterized for Future Suppliers

The generator is rebuilt as a reusable system: `generate_supplier_set.py --state TX --supplier "Austin DME" --patients 30 --challenge-level high`

This accepts: state abbreviation, supplier name, patient count, challenge level (low/medium/high). It automatically loads the correct payer strings, geographic patient data, and prescriber affiliations for that state from a `market_data.json` config file. A new pilot in Texas, Florida, or Ohio requires no code changes — just add the state's market data to the config and run the generator.

This is the CSV Agent's primary output: a reusable generator system, not just a batch of files.

### PA Set (25 Files) — Philadelphia/Southeastern PA Market

Payer strings: "Medicare Part B", "Medicare", "PA Medicaid", "Keystone First", "UPMC Health Plan", "Highmark BCBS", "Aetna PA", "Independence Blue Cross", "Geisinger", "AmeriHealth Caritas PA"

Patient geography: Philadelphia, Bucks County, Montgomery County, Chester County  
Prescribers: Penn Medicine, Jefferson Health, Temple Health  
Supplier fields: "Gaboro DME", "Branch: PA-001", "State: PA"

### NJ Set (25 Files) — Northern NJ / Metro NY Area

Payer strings: "Medicare Part B", "Medicare", "NJ FamilyCare", "Horizon BCBS NJ", "Aetna NJ", "Cigna NJ", "AmeriHealth NJ", "WellCare NJ", "UnitedHealthcare NJ", "Oxford Health"

Patient geography: Bergen County, Essex County, Hudson County, Passaic County  
Prescribers: Hackensack Meridian, RWJBarnabas, Atlantic Health  
Supplier fields: "Gaboro DME", "Branch: NJ-002", "State: NJ"

### State-Change Patients (Both Sets)

6 patients per set whose status evolves across the file sequence, proving Signal's cycle reset and priority recalculation work across multiple imports:

- Starts as "Renewal Due SOON" (no visit date) → progresses to Active after Confirm Visit in file 10 → new cycle visible by file 20
- Starts as "Refill Window" → advances to Active after new shipment detected in import diff
- Starts as Active → slides into Renewal Due SOON as dates age
- Transferred patient: appears mid-sequence, starts as "Needs Verification", clears to Active after staff confirms documentation

### Challenge Types (Both Sets)

- All 25 header variants from existing generator, adapted to PA/NJ market
- Date format variations: MM/DD/YYYY, YYYY-MM-DD, M/D/YY, "Jan 15 2026", "15-Jan-2026", YYYYMMDD, ISO datetime with time
- Extra noise columns: notes, billing codes, staff initials, auth numbers
- Missing optional columns: some files omit component, some omit quantity
- Null/empty values in 2-3 required columns (3-4 files)
- Future shipment dates (2-3 files)
- Malformed dates: "not on file", "pending", "TBD" in date columns (2 files)
- Visit date column present but empty (2 files — should fall back to estimate)
- PA status columns with varying labels: "auth_status", "PA Status", "Prior Auth", "PA"
- Transfer patient columns: "Transfer_From", "Previous Supplier", "Transfer Status"
- Rows where quantity is zero or negative (edge case)
- Duplicate patient_id within same file (should be caught and flagged)

---

## Section 6: Watcher Agent

### Problem

Signal applies rules from payer_rules.json. When CMS, a MAC, or a payer changes CGM coverage requirements, Signal continues applying the old rules silently. Suppliers find out after the fact — claims denied, compliance gaps, Synapse Health-style surprises.

### Design

A background monitoring agent runs on a defined cadence (daily or weekly). It monitors:

- CMS.gov for CGM-related coverage policy changes
- MAC websites (Noridian, CGS, Palmetto GBA, etc.) for local coverage determination updates
- Synapse Health announcements for mandatory enrollment changes
- Key payer websites for PA requirement changes affecting CGM
- Federal Register for DMEPOS-related proposed and final rules

When a potentially relevant change is detected:

1. Watcher Agent creates a "Rule Change Alert" record
2. Kisa receives an alert (via Telegram/NavBot and email) with: what changed, source, date, which patients in Signal are affected
3. Kisa reviews and approves or dismisses
4. On approval: payer_rules.json is updated, Signal recalculates affected patients' statuses, worklist reflects new requirements
5. Suppliers see updated worklist with a banner: "Documentation requirements updated [date] — [brief description]"

This prevents the silent failure mode. Suppliers are never running on stale rules without knowing it.

### MVP Scope

For the demo and pilot, the Watcher Agent is mentioned as a capability ("Signal monitors for rule changes so your team is never caught off guard") but is not fully deployed. It is built and running in background mode, alerting Kisa only. Supplier-facing alerts are Phase 2.

---

## Section 7: Demo Flow (15 Minutes, Kisa Drives)

**Beat 1 — Name the Problem (2 min, verbal):**
"Right now your team works backwards. A claim comes back denied. Someone digs into the chart. The 6-month qualifying visit was never confirmed before the order went out. By then you can only appeal it. Signal catches it before the claim goes out."

**Beat 2 — Show the Worklist (5 min):**
Upload CSV. 30-40 patients load. Worklist appears sorted by urgency. Walk to a Renewal Due Critical patient (red, bold). Expand row. Show cascade: "Qualifying visit not confirmed → SWO validity at risk → next shipment blocked." Say: "This is what flummoxes your organization. Signal shows it, assigns the priority, and tells your staff what to do."

Click Confirm Visit. Enter a prescriber-confirmed date. Status updates live to Active. "That date is in Signal permanently."

**Beat 3 — Show Range and Utility (5 min):**
Show Supply Lapsed patient at top — full documentation cascade, most urgent. Show Active patient — all five items green, Next Visit Due in 4 months. "Your team spends zero time on this one." Export worklist. "This is what your team opens Monday morning."

**Close (3 min):**
"We are piloting with three organizations. I want Gaboro to be one of them. I have a pilot agreement for you — no charge for 90 days, and as a founding partner your rate is locked at $199/month for life."

---

## Section 8: Legal Documents

### Pilot LOI (STTIL Solutions to Gaboro DME)

Scope: Gaboro uploads de-identified CSV data; Signal produces a prioritized documentation worklist; Gaboro staff acts on it.

Key terms:
- 90-day pilot, no charge
- At conversion: $199/month Worklist tier, locked for life as founding pilot partner
- STTIL gets: feedback rights, anonymized case study rights with Gaboro's written approval
- **Reference rights:** Gaboro grants STTIL the right to name Gaboro as "an engaged pilot partner of Signal" in investor and marketing materials, subject to Gaboro's approval of specific usage
- Termination: 30 days written notice, data deletion within 10 business days with written confirmation
- Governing law: Pennsylvania
- Data: de-identified only during pilot (patient_id, device_type, shipment_date, payer — no PHI)

### NDA (Mutual)

Covers: both parties' confidential information including patient workflow descriptions, pricing structures, product roadmap, supplier operational data.

Standard carve-outs: publicly available information, independently developed information, information received from a third party without restriction.

DMEPOS-specific clause: DMEPOS operational workflows and documentation processes shared during the pilot are proprietary and covered under this agreement.

Duration: 2 years. Governing law: Pennsylvania.

### Drafting Pattern (Jakub Method)

Legal Lead Agent manages 10-15 sub-agents: research agents (DMEPOS pilot agreement standards, PA governing law, healthcare SaaS LOI precedents), drafting agents (one per major section), review agent (consistency, missing provisions, ambiguous language). Lead agent assembles final drafts.

Output: markdown files to signal/pitch/legal/. Both documents to Nixon Law Group (Clyde) for 30-minute attorney review before Tuesday.

---

## Section 9: Compliance Items (First Supplier Gate)

Run in parallel with the build. Must be complete before Robert uploads any data:

- Privacy Policy published at stable public URL
- Incident response procedure written (includes breach notification timeline)
- Data handling / minimum necessary fields documentation written
- Audit log WORM enforcement (RLS policy blocking UPDATE/DELETE on audit_log)
- MFA confirmed on all admin accounts (Railway, Supabase, Vercel, Clerk)
- payer_rules.json quarterly update cadence documented
- Supabase plan tier confirmed and PHI posture documented

---

## Section 10: Agent Team

**Build Agent**
Implements: Confirm Visit workflow (button, modal, Supabase persistence, live recalculation), visit date priority chain in coverage_calculator.py, full documentation state machine (5 items, payer-dependent), CSV diff logic for cycle reset, 90/60/45 priority tier system with "Renewal Due SOON" labeling, Amber/Amber-Bold/Red-Bold visual system, 45-day supplier outreach flag, transferred patient detection and "Needs Verification" status, existing client cold-start logic (estimated proxy labeled), bug fixes, placeholder removal, smoke tests, end-to-end export verification.

**CSV Generator Agent**
Builds `generate_supplier_set.py` (parameterized reusable system), `market_data.json` (state-to-payer-names config), `generate_pa_set.py`, `generate_nj_set.py`. Outputs 50 files to test-data/pa-set/ and test-data/nj-set/. Includes state-change patients, transferred patients, all challenge types.

**Bug Hunter Agent**
Runs all 50 CSVs through Signal backend normalizer and coverage calculator. Returns structured failure report: filename, error type, line number, recommended fix. Feeds to Build Agent for resolution.

**Legal Lead Agent (Jakub pattern)**
10-15 sub-agents research and draft LOI and NDA. Output to signal/pitch/legal/.

**Compliance Docs Agent**
Privacy Policy, incident response procedure, data handling documentation. Output to signal/docs/compliance/.

**Watcher Agent**
Monitors CMS, MAC websites, Synapse Health, key payer sites for CGM rule changes. Alerts Kisa via NavBot/email. payer_rules.json updates require Kisa approval before taking effect.

**NavBot (@STTILness_bot)**
Domain research support via Telegram during the build. Priority today: PA/NJ payer name variants for CSV accuracy, CGM qualifying visit regulatory language for legal docs.

---

## Section 11: Pilot Prep Questions for Robert (Added to /pilot-prep)

1. When supplies ship, how does your team know — auto-recorded in Brightree or Tenovi, or manual?
2. How often does your team export from Brightree and what triggers it?
3. Does your CSV export include a ship date column and what is it labeled?
4. What percentage of your CGM patients are Medicare Advantage vs. traditional Medicare vs. Medicaid?
5. Do you track PA status per patient in Brightree and is it in your standard CSV export?
6. Is SWO tracking in Brightree or a separate system?

---

## Section 12: What We Are Not Building This Cycle

- Patient outreach of any kind — Signal never contacts patients, now or in the future. Prescriber outreach (Phase 2 fax facilitation) is the only direct communication Signal will support.
- Column mapping review UI (verbal in demo)
- Brightree/NikoHealth API (Phase 2)
- Patient-facing features
- Real PHI handling
- Token generation service (Med Tracker prerequisite — Phase 3)
- Doc upload and AI validation (explicitly deferred)
- Consortium features
- Any item in the Phase 2/3 tabled list in Signal CLAUDE.md

---

## Target Pilot Readiness After This Build

- **Pilot Readiness:** 13/13 PASS (up from 4/13 = 31%)
- **Compliance Gate (Pilot):** 14/15 PASS
- **Compliance Gate (First Supplier):** 8/15 PASS (Privacy Policy, LOI, NDA, data handling, incident response addressed this build)

---

## Spec Self-Review

**Placeholders:** None. All sections complete.  
**Consistency:** Documentation state machine matches Confirm Visit workflow. CSV state-change patients match cycle reset logic. LOI $199 lifetime rate matches demo close language. Transferred patient detection matches CSV challenge types.  
**Scope:** Appropriate for a single implementation plan. Legal, compliance, CSV generation, and core build are parallel workstreams with no sequential blocking dependencies.  
**Ambiguity resolved:** 45-day trigger = supplier outreach flag only, not automated patient text. Cycle reset = CSV re-import diff, not manual button. Visit confirmation = prescriber-sourced only, not patient-reported. All stated explicitly.
