diff --git a/CLAUDE.md b/CLAUDE.md index c1c5878..6e929d1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,7 +64,7 @@ and stays predictable. Whitepaper: `/Users/sttil-solutions/Documents/Obsidian_Vault/STTIL-Vault/Projects/2026-05-18-pilot-readiness-whitepaper.md` -### Checklist Status (as of 2026-06-11) — 92% pilot-ready (12/13) +### Checklist Status (as of 2026-06-16) — 100% pilot-ready (13/13) | Checklist Item | Status | |---|---| @@ -76,7 +76,7 @@ Whitepaper: `/Users/sttil-solutions/Documents/Obsidian_Vault/STTIL-Vault/Project | Report generation calculates from backend | PASS | | Each status has reason + recommended action | PASS — visit date proxy bug fixed 2026-06-09; `_resolve_visit_date()` implements full priority chain (CSV column > Supabase confirmed > shipment-30d estimate) | | Export CSV works and opens cleanly | PASS — verified end to end 2026-06-10 | -| Placeholder content removed | PARTIAL — StatCard undefined variables fixed 2026-06-09; no empty-state guidance or status legend for first-time users | +| Placeholder content removed | PASS — StatCard undefined variables fixed 2026-06-09; empty state heading "Drop your file here" + StatusLegend below; stoplight colors + ✓ for Clear to Ship; tab counts and percentages; legend bar removed from worklist header — all deployed 2026-06-16 | | Browser smoke test passes | PASS — CSV import, all filter tabs, Confirm Visit, Export all verified 2026-06-10; sidebar count sync fixed | | Data handling rules documented | PASS — privacy-policy.md + data-handling.md written 2026-06-07; minimum necessary fields, CSV disposition policy, retention, and payer_rules.json cadence all documented | | Real PHI blocked | PASS — architecture confirmed; Supabase Pro plan verified 2026-06-11 | diff --git a/docs/superpowers/specs/2026-06-15-signal-intelligence-spec.md b/docs/superpowers/specs/2026-06-15-signal-intelligence-spec.md new file mode 100644 index 0000000..e3bf99d --- /dev/null +++ b/docs/superpowers/specs/2026-06-15-signal-intelligence-spec.md @@ -0,0 +1,296 @@ +# Signal Intelligence — Architecture Spec +**Date:** 2026-06-15 +**Status:** Approved concept, Phase 1 build next session +**Product tier:** Signal Tier 3 — Intelligence ($699-999/month + usage) +**Approved by:** Kisa Fenn + +--- + +## What Signal Intelligence Is + +Signal (Tier 1) gives a DMEPOS supplier a prioritized worklist of documentation gaps from their CSV. Signal Intelligence gives them something more valuable: a continuously monitored regulatory environment where rule changes are detected before they create denials, scored for significance, and acted on only after human approval. + +Internally, Kisa runs Signal Intelligence first. Her 30 years of managed care expertise is the governance layer — she reviews every synthesized finding before it flows to product, content, or payer rules. When the product is sold to Tier 3 subscribers, their administrator becomes the human-in-the-loop for their organization. + +**The core premise:** Agents gather and validate. Kisa (or the supplier admin) decides. Nothing acts without explicit approval. + +--- + +## Architecture — Three Layers + +### Layer 1: Intake and Validate + +**Runs:** Daily (scheduled n8n cron) +**What it does:** Fetches sources, validates them, stores validated findings in TriLane. + +Every finding passes two gates before entering TriLane as confirmed intelligence: + +**Gate 1 — Source Domain Validation** +URL must match an approved domain list: +- `.gov` (all government domains) +- `.cms.gov`, `.hhs.gov`, `.medicaid.gov`, `.medicare.gov` +- MAC domains: noridian.com, cgsadmedicare.com, palmettogba.com, ngsmedicare.com, hhcsc.com, cahaba.com +- PubMed Central: ncbi.nlm.nih.gov/pmc +- Approved journals: jama.network.com, tandfonline.com, healthaffairs.org, wiley.com (JAGS), mddionline.com +- Anything else → quarantine, flagged "unverified — human review required" + +**Gate 2 — Content Grounding Check** +Claude reads the actual source text and confirms the finding against it. Not a summary from memory — verification against the retrieved document. Any finding Claude cannot ground in the source text is quarantined. + +**Gate 3 — Author Verification** +Applies to bylined articles only. Government agency publications (CMS, OIG, MAC sites) have no individual byline — domain authority is sufficient, Gate 3 is skipped. + +For peer-reviewed journal articles: +- Extract author names and claimed institutional affiliation from article metadata +- Check ORCID (orcid.org public API — best academic ID system, free): search by name + institution +- Check PubMed author profile if ORCID not found +- Check article's own institutional disclosure for matching faculty/researcher page +- If ORCID or PubMed match confirms author at listed institution: verified ✓ +- If author found but institution doesn't match article claim: flagged — Kisa review required +- If no ORCID, no PubMed, no findable institutional page: quarantined — reason recorded as "author unverifiable — no public academic record" + +For industry publications (AAHomecare, Healthcare IT News, MDDI): +- Authors are journalists or analysts, not academics — check LinkedIn or outlet's own author page or byline history +- Complete ghost author with no findable presence anywhere: quarantine with reason recorded +- Partial presence (LinkedIn only, no byline history): flagged for Kisa review, not auto-discarded + +**Quarantine rule:** Anything that fails Gate 3 is removed from the intelligence pipeline. The reason is recorded in the quarantine table. Nothing questionable is kept. If an author can't be confirmed publicly, the article doesn't enter TriLane — regardless of how good the content looks. + +Findings that pass all three gates are stored in TriLane (Signal Intelligence workspace, to be created) with: +- Source URL +- Domain authority rating (government = 3, MAC = 2, peer-reviewed journal = 1) +- Date retrieved +- Raw excerpt used for grounding +- Preliminary topic tags + +Quarantined findings go to a separate NocoDB table for optional manual review. + +--- + +### Layer 2: Analyze and Score + +**Runs:** Weekly (Sunday night, results ready Monday morning) +**What it does:** Synthesizes validated findings into a structured brief for Kisa. + +The weekly synthesis agent groups all validated findings from the past 7 days by theme and does three things: + +**Directional signal counting** +Each finding is tagged by direction: +- Pharmacy channel expansion (negative for DME suppliers) +- PA requirement increase (negative) +- PA exemption expansion (positive) +- CGM coverage expansion (positive) +- Enrollment/PECOS requirement change (neutral to negative) +- Competitive bidding update (variable) + +Frequency of signals by direction = significance proxy. This is not chi-square statistical testing — it is structured frequency counting that tracks directional momentum over time. As the dataset grows (30+ days), trends become visible. + +**Contradiction flagging** +When two validated government sources point in opposite directions on the same topic, both are surfaced explicitly with their dates and source authority ratings. Contradictions are never averaged away. Kisa sees both sides. + +**Brief format delivered to Kisa via Telegram:** +``` +SIGNAL INTELLIGENCE — Weekly Brief [date] + +DIRECTIONAL SIGNALS THIS WEEK: +- Pharmacy shift (MA): 3 signals ↑ [moderate confidence] +- PA exemption: 1 signal ↑ [low confidence — single source] +- Synapse Health: 2 signals [compliance deadline reinforced] + +TOP FINDINGS: +1. [Source] [Date] — [One sentence finding] [Domain authority: 3] +2. [Source] [Date] — [One sentence finding] [Domain authority: 2] + +CONTRADICTIONS: [none this week / "CMS draft vs MAC guidance on X"] + +CONTENT OPPORTUNITIES: +- "[Finding 1] is defensible for LinkedIn — source: [URL]" + +PAYER RULES FLAGS: +- "[MA plan X changed PA requirement for CGM] — payer_rules.json Section Y needs review" + +[Approve all] [Review individually] [Dismiss all] +``` + +Kisa reviews. Approve → items flow downstream. Dismiss → archived with reason. Review individually → Telegram sends each finding separately with Approve/Dismiss buttons. + +**Nothing flows downstream without Kisa's explicit approval.** + +--- + +### Layer 3: Distribute + +**Triggers:** Kisa approval of Layer 2 brief +**Two outputs:** + +**Content calendar feed** +Approved findings with content opportunity flag → new row in NocoDB Content Schedule table with: +- Status: Draft +- Source URL (the defensible citation) +- Suggested angle (problem frame / investor frame / data frame) +- Raw finding text + +`lead-content` agent picks up Draft items on the weekly content review. Posts are grounded in validated government or peer-reviewed sources by design. + +**payer_rules.json flags** +Approved findings that affect payer rules → a flag in NocoDB with: +- Which payer_rules.json section is affected +- What changed +- Source URL +- Kisa's approval timestamp + +A build session converts approved flags into payer_rules.json updates. Signal recalculates affected patients. Suppliers see an updated worklist with a banner: "Documentation requirements updated [date] — [description]." + +--- + +## Agent Queue Architecture + +### The Queue Table (NocoDB: `intelligence_queue`) + +| Field | Values | +|---|---| +| id | UUID | +| task_type | fetch_source / validate / score / synthesize / notify_kisa / update_payer_rules | +| status | pending / claimed / in_progress / done / failed / awaiting_review | +| assigned_agent | null or agent_id | +| claimed_at | timestamp | +| priority | 1 (urgent) to 5 (low) | +| payload | JSON — the task data (URL, finding text, etc.) | +| result | JSON — the output | +| error_log | text — failure reason if failed | + +### Homogeneous Workers + +Any agent can claim any task type. When an agent finishes its assigned task, it checks the queue for overflow in any category and picks up the next pending item. No agent is ever idle while work is pending. + +**Atomic claim protocol:** When an agent claims a task, it sets `status = claimed` and `claimed_at = now()` in a single atomic operation. No two agents can claim the same task. NocoDB PATCH with a conditional filter enforces this. + +**Timeout recovery:** A watchdog workflow runs hourly. Any task where `status = in_progress` and `claimed_at` is more than 30 minutes ago is reset to `status = pending` and logged as a stall. The task is picked up on the next cycle. Nothing is permanently lost. + +**Idempotency:** Each task has a unique ID derived from source URL + date. The same source+date combination never creates two queue entries. Safe to retry. + +### The Loop Pattern + +For daily intake: n8n Schedule Trigger → worker claims tasks → processes → marks done → checks for overflow → exits when queue is empty. + +For weekly synthesis: n8n Schedule Trigger (Sunday 10pm) → synthesis agent claims all pending score tasks from past 7 days → generates brief → creates notify_kisa task → Telegram sends brief with approval buttons → Kisa responds → downstream tasks created. + +For longer coordination tasks (legislative projection, deep synthesis): Claude Code `/loop` skill runs in session with self-pacing. Each iteration claims items from the queue, processes them, stores results in TriLane, and continues until queue is clear. + +**Bottleneck handling:** Failed tasks log their error and reset to pending. A daily summary to Telegram reports: tasks processed, tasks failed, tasks quarantined. Nothing fails silently. + +--- + +## Source List (Starting Set) + +**RSS feeds — wire immediately:** +1. Federal Register DMEPOS rules: `https://www.federalregister.gov/api/v1/documents.rss?conditions[agencies][]=Centers%20for%20Medicare%20%26%20Medicaid%20Services&conditions[type][]=Rules` +2. JAMA Health Forum: `https://jamanetwork.com/journals/jama-health-forum/feeds/rss` +3. Health Affairs Blog: `https://www.healthaffairs.org/blog/feed/` +4. Healthcare IT News: `https://www.healthcareitnews.com/feed/rss` +5. MDDI (Medical Device & Diagnostic Industry): `https://www.mddionline.com/feed` +6. Journal of the American Geriatrics Society: `https://onlinelibrary.wiley.com/feed/rss/2.0/1000_jags` +7. State Medicaid Director Letters (CMS): `https://www.medicaid.gov/federal-policy-guidance/federal-policy-letters/index.html` +8. Health Affairs (main): `https://www.healthaffairs.org/action/showFeed?type=etoc&feed=rss` + +**URL-scrape sources (weekly hash-compare):** +9. CMS MLN Updates: `https://www.cms.gov/outreach-and-education/outreach/ffsprovpartprog/provider-partnership-email-archive` +10. HCPCS quarterly updates: `https://www.cms.gov/medicare/coding-billing/healthcare-common-procedure-coding-system-hcpcs-codes` +11. AAHomecare news: `https://www.aahomecare.org/news` +12. OIG fraud alerts: `https://oig.hhs.gov/fraud/consumer-alerts/` + +**State-specific (add per active pilot state):** +- PA Medicaid: `https://www.dhs.pa.gov/providers/Providers/Pages/Medical/Bulletins-and-Updates.aspx` +- NJ Medicaid: `https://www.njmmis.com/ProviderInfo.aspx` +- Add NY, OH when pilots expand + +**Source table lives in NocoDB** — add/remove rows to change monitoring scope, no workflow code changes required. + +--- + +## Graphify Integration + +Every 30 days, run graphify on the Signal Intelligence TriLane workspace. The knowledge graph reveals: +- How CGM coverage rules are evolving over time +- Which payers are leading vs. lagging on pharmacy channel shift +- Which clinical evidence themes are driving coverage expansion +- Where contradictions persist between sources + +This becomes the foundation for: +- Whitepapers (all claims traceable to graph nodes) +- LinkedIn content (defensible, cited) +- Investor narratives (evidence-backed market thesis) +- Signal's own payer_rules.json updates (grounded in sourced intelligence) + +--- + +## Human-in-the-Loop Protocol + +Kisa's managed care expertise is the product's core intellectual property. Agents gather and validate. Kisa decides. This is not a bottleneck — it is the intelligence layer agents cannot replicate. + +**Approval required before:** +- Any finding enters the content calendar +- Any payer_rules.json flag converts to a code change +- Any legislative projection is published externally +- Any finding is cited in marketing materials + +**Kisa's context that agents cannot know:** +- Historical MAC behavior patterns (which proposed rules become final) +- Payer-specific relationships and track records +- Operational context from supplier conversations +- Political and regulatory timing signals from industry relationships + +The governance brief is designed to surface findings concisely so Kisa can apply this context quickly. Target: under 5 minutes per weekly brief review. + +--- + +## Signal Intelligence as Tier 3 Product + +When sold to suppliers: +- Supplier admin replaces Kisa as the human-in-the-loop +- The governance brief is supplier-specific (only rules affecting their payers and states) +- payer_rules.json updates flow automatically after admin approval +- Worklist reflects current requirements without supplier staff reading the Federal Register +- Suppliers receive a monthly intelligence summary they can share with their compliance teams + +**Pricing:** $699-999/month + Claude API usage passthrough at cost +**Target buyers:** Billing companies (scale = value), large DMEPOS groups (multi-state complexity = value) +**Sales motion:** Demo the internal STTIL version first. "We built this to run Signal ourselves. We're making it available to Tier 3 subscribers." + +--- + +## Phase Roadmap + +**Phase 1 — Foundation (next build session)** +- n8n Watcher Agent: fetch 8 RSS sources + 4 URL-scrape sources +- Domain validation gate (Gate 1) +- TriLane Signal Intelligence workspace created +- Storage of validated findings with metadata +- Weekly Telegram summary (no approval buttons yet — simple notification) +- Estimated build: 2-3 hours + +**Phase 2 — Governance Layer (following session)** +- Gate 2: content grounding check +- NocoDB intelligence_queue table +- Homogeneous worker pattern +- Telegram inline approval buttons (approve/dismiss per finding) +- Content calendar feed (approved findings → NocoDB Draft) +- payer_rules.json flag system +- Estimated build: 3-4 hours + +**Phase 3 — Graphify + Projection (after 30 days of data)** +- Graphify run on Signal Intelligence TriLane workspace +- Directional trend visualization +- Legislative projection brief format +- Contradiction tracking +- Estimated build: 2 hours + ongoing graphify runs + +**Phase 4 — Subscriber version** +- Multi-tenant governance (supplier admin as human-in-the-loop) +- State-filtered source lists per subscriber +- Monthly intelligence report as PDF +- This is the Tier 3 product shipped to paying customers + +--- + +*Spec reflects architecture confirmed in conversation 2026-06-15. Build starts Phase 1 next session.* diff --git a/signal-ui/src/components/EmptyState.jsx b/signal-ui/src/components/EmptyState.jsx index cac2395..47d7d3c 100644 --- a/signal-ui/src/components/EmptyState.jsx +++ b/signal-ui/src/components/EmptyState.jsx @@ -1,4 +1,5 @@ import { useState } from "react"; +import StatusLegend from "./StatusLegend"; export default function EmptyState({ onOpenFile, onDropFile }) { const [dragActive, setDragActive] = useState(false); @@ -71,7 +72,7 @@ export default function EmptyState({ onOpenFile, onDropFile }) { lineHeight: "1.5", }} > - or click below to browse + {dragActive ? "Release to load" : "or click below to browse"}

- ))} + {FILTERS.map((f) => { + const count = tabCounts[f.key] ?? 0; + const pct = total > 0 && f.key !== "all" ? Math.round((count / total) * 100) : null; + const isActive = activeFilter === f.key; + const indicatorColor = isActive ? "white" : f.color; + return ( + + ); + })} - {/* Status legend — color key for the four status tiers */} - {localRecords.length > 0 && } - {/* Working-on banner */} {activePatientId && (
- +