clinical-data-reconciliation-skill

Clinical Data Reconciliation Skill

An enterprise-grade, cloud-native Agent Skill designed to run seamlessly in Gemini Enterprise App, Antigravity, and any agent harness supporting SKILL.md or Canvas UI iframe extensions.

This skill automates monthly clinical data quality reconciliation, Pay-for-Performance (P4P) score calculations, HL7v2 and C-CDA standard terminology audits, regulatory drift detection, BigQuery Gold tier view DDL generation, Looker semantic layer synchronization, and interactive Canvas UI dashboards with Clinical Knowledge Graph visualizers.

---

Executive Overview & Core Capabilities

The primary objective of the Clinical Data Reconciliation Skill is to automate the extraction, validation, reconciliation, and reporting of monthly clinical data quality rules across healthcare data platforms.

The skill operates directly across Google Cloud Storage (GCS) and BigQuery Bronze, Silver, and Gold datasets containing parsed HL7v2 messages and C-CDA XML/JSON documents. It evaluates data quality against digital health plan quality scorecards, USCDI v2/v3 specifications, and legacy VBA macro logical rulesets.

Key functional capabilities include:

• Declarative Rule Ingestion: Ingesting and dynamically parsing custom health plan rubrics and federal USCDI standards into structured validation rules.
• HL7v2 Discharge Disposition Validation: Auditing HL7v2 PV1-36 fields against plan-approved code sets (HL7 Table 0112 / UB-04 FL 17) to compute field quality ratings.
• C-CDA Medication Standards Auditing: Auditing medication entries to enforce standard RxNorm terminology (OID 2.16.840.1.113883.6.88 / RxCUI) over local proprietary codes.
• Regulatory & Rubric Drift Detection: Detecting discrepancies when code whitelists, pass thresholds, or USCDI federal standards (v2 vs v3) evolve.
• Interactive Canvas UI Dashboards: Generating standalone single-page visual dashboards with live KPI metric tiles, search-and-filter facility matrices, and expandable diagnostic drawers.
• Clinical Knowledge Graph Visualization: Interactive network graph visualizer modeling relationships between federal standards, terminologies, rubrics, EHR vendors, hospital facilities, and flagged code violations.
• "What-If" Threshold Simulator: Interactive range slider enabling quality planners to dynamically simulate network compliance impacts under varying P4P threshold requirements.
• Automated Provider Remediation Sandbox: Generating actionable EHR interface mapping remediation memos for hospital clinical informatics teams.
• BigQuery Gold DDL Generation: Creating optimized BigQuery standard SQL validation queries and versioned Gold tier scoring views (CREATE OR REPLACE VIEW DDL).
• Looker Semantic Layer Synchronization: Generating LookML View (.view.lkml) and Explore (.model.lkml) definitions for self-service business intelligence dashboards directly on BigQuery without duplicating data.

---

Architecture & 5 Core Functional Modules

 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                             Input Data Ingestion                            │
 │   • Health Plan Rubrics (YAML/JSON)          • USCDI Standards (v2 / v3)    │
 │   • Bronze/Silver HL7v2 Datasets             • Bronze/Silver C-CDA Datasets │
 │   • Legacy VBA Macro Rules                   • Provider / Hospital Registry │
 └──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                         Clinical Reconciliation Engine                      │
 │                                                                             │
 │  [Module A: Rule Ingestion & In-Memory Parsing]                             │
 │  • Dynamic schema extraction • Code whitelists • Pass/Fail thresholds       │
 │                                                                             │
 │  [Module B: Automated Quality Scan & Scoring Engine]                        │
 │  • HL7v2 PV1-36 evaluation   • C-CDA RxNorm audit • P4P composite weighting │
 │                                                                             │
 │  [Module C: Drift & Discrepancy Detection]                                  │
 │  • Regulatory USCDI drift    • Health plan code drift • Non-compliant flags │
 │                                                                             │
 │  [Module D: Self-Correction & SQL View Updates]                             │
 │  • BigQuery Gold DDL generator • Historical version matrix management       │
 │                                                                             │
 │  [Module E: Canvas UI & Downstream Visualization Orchestration]             │
 │  • Interactive Canvas HTML Dashboard • Cytoscape.js Clinical Knowledge Graph│
 │  • What-If Threshold Simulator • Provider Remediation Studio • LookML Sync  │
 └──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                             Actionable Outputs                              │
 │   • Interactive Canvas HTML Dashboard (scorecard_plan-alpha_2026_01.html)   │
 │   • Clinical Knowledge Graph JSON Model (..._knowledge_graph.json)          │
 │   • Multi-Format Scorecards (JSON, CSV, Executive Markdown)                 │
 │   • BigQuery Gold Tier Views (v_gold_clinical_quality_scores_YYYY_MM)       │
 │   • LookML Semantic Layer (clinical_quality_scores.view.lkml)               │
 │   • Provider Remediation Action Plans & Flagged Local Code Distributions    │
 └─────────────────────────────────────────────────────────────────────────────┘

Module Breakdown:

• Module A: Rule Ingestion & In-Memory Parsing

  • Ingests health plan quality rubrics (YAML/JSON), USCDI standards, and legacy VBA macro rulesets.
  • Extracts validation criteria, approved code whitelists, required fields, and score thresholds.

• Module B: Automated Quality Scan & Query Execution

  • HL7v2 Discharge Disposition Evaluation: Scans HL7v2 PV1-36 fields against plan-approved codes (e.g., 01, 02, 03, 06, 20), detects invalid codes or unmapped text (DISCH HOME), and computes compliance percentages.
  • C-CDA Medication Standard Audit: Scans C-CDA XML/JSON documents for standard RxNorm coding (OID 2.16.840.1.113883.6.88 / RxCUI) versus local proprietary codes (HOSP-LOCAL-501, EPIC_CUSTOM_MET).
  • BigQuery SQL Generation: Programmatically outputs optimized Standard SQL queries with CTEs for Bronze/Silver data validation.

• Module C: Drift & Discrepancy Detection

  • Detects regulatory drift between USCDI versions (v2 vs v3) and rubric updates (code additions/removals, threshold changes).
  • Flags non-compliant hospital sources and EHR systems with remediation priority ratings.

• Module D: Self-Correction & SQL View Updates

  • Automatically drafts CREATE OR REPLACE VIEW DDLs for BigQuery Gold tier datasets embedding active rubric rules.
  • Maintains a version-controlled rules matrix allowing historical monthly datasets to be audited against the exact rules active during that transaction month.

• Module E: Canvas UI & Downstream Visualization Orchestration

  • Interactive Canvas HTML Dashboard: Standalone single-page application rendered directly in agent Canvas iframes.
  • Clinical Knowledge Graph: Cytoscape.js-powered interactive network mapping standards, terminologies, rules, EHR vendors, facilities, and violations.
  • What-If Sensitivity Simulator: Dynamic pass-rate modeling tool.
  • Multi-Format Exports: JSON, CSV, Executive Markdown, and Looker LookML semantic layer definitions.

---

Interactive Canvas UI & Clinical Knowledge Graph Suite

The skill includes native Canvas UI support designed for agent environments with visual iframe panels (such as Gemini Enterprise App, Spark, and Antigravity).

 ┌───────────────────────────────────────────────────────────────────────────────────────┐
 │ 🏥 Clinical Data Quality & P4P Executive Dashboard                   [Export JSON/CSV]│
 ├───────────────────────────────────────────────────────────────────────────────────────┤
 │ [ 📊 Executive P4P Dashboard ]  [ 🕸️ Knowledge Graph ]  [ ⚖️ Drift ]  [ 🛠️ Remediation ] │
 ├───────────────────────────────────────────────────────────────────────────────────────┤
 │                                                                                       │
 │  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐              │
 │  │ Overall P4P   │ │ Passing Facs  │ │ Records Audited│ │ Active Drift │              │
 │  │    91.7%      │ │   3 / 4       │ │     240       │ │  1 Detected │              │
 │  │ [PASS >=85%]  │ │   (75.0%)     │ │ HL7v2 + CCDA  │ │ USCDI v2->v3│              │
 │  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘              │
 │                                                                                       │
 │  ┌─────────────────────────────────────────────────────────────────────────────────┐  │
 │  │ 🎛️ P4P Passing Threshold Simulator: [===== 85.0% =====] (Simulate Network Impact)│  │
 │  └─────────────────────────────────────────────────────────────────────────────────┘  │
 │                                                                                       │
 │  ┌───────────────────────────────────────┐ ┌───────────────────────────────────────┐  │
 │  │ Facility Performance Matrix           │ │ Interactive Clinical Knowledge Graph  │  │
 │  │ Filter: [ All EHRs ▼ ] [ Search...  ] │ │   (USCDI v3) ──► [PV1-36 Disp]        │  │
 │  │ ───────────────────────────────────── │ │         │              │              │  │
 │  │ St. Jude Memorial   | Epic   | 91.7%  │ │   [Health Plan]        ▼              │  │
 │  │ Valley Regional     | Cerner | 83.3%  │ │         │       (St. Jude Epic)       │  │
 │  │ Pinecrest Healthcare| Medit. | 73.3%  │ │         ▼              │ (Violation)  │  │
 │  │ Metro Urgent Care   | Legacy | 61.7%  │ │   [C-CDA RxNorm] ──► [MED_CATALOG_440]│  │
 │  └───────────────────────────────────────┘ └───────────────────────────────────────┘  │
 └───────────────────────────────────────────────────────────────────────────────────────┘

Visual Modules & Capabilities:

1. 📊 Executive P4P Reconciliation Dashboard

   • Hero Metric Tiles: Real-time KPI cards displaying Overall P4P Score, Facility Pass Rates, Total Evaluated Records, and Active Drift Warnings.
   • 🎛️ "What-If" Threshold Simulator: Real-time slider (50% to 100%) that allows quality managers to test the financial and compliance impact of changing pass thresholds without re-running data pipelines.
   • Facility Matrix with Search & Filtering: Client-side filtering by hospital name, EHR vendor (Epic, Oracle Cerner, MEDITECH, Legacy EHR), and pass/fail status.
   • Diagnostic Inspection Drawer: Expandable slide-over modal for deep-diving into individual provider metrics, non-compliant reasons, and detected non-standard codes.

2. 🕸️ Interactive Clinical Knowledge Graph

   • Full Network Graph Visualizer (Cytoscape.js): Interactive graph mapping federal standards (USCDI v2/v3), standard vocabularies (RxNorm, UB-04 Table 0112), health plan rubrics, EHR vendors, provider facilities, and flagged invalid local codes.
   • Multiple Layout Options: Switch between Force-Directed (cose), Hierarchical (breadthfirst), Concentric Rings, and Circular layouts.
   • Interactive Node Inspector: Click on any node to view incoming/outgoing relationships, data bindings, compliance scores, and remediation recommendations.
   • Semantic Color Coding: Federal Standards (Blue), Quality Rules (Teal), Health Plan Rubrics (Purple), EHR Vendors (Orange), Passing Facilities (Green), Failing Facilities / Violations (Red), and Drift Alerts (Amber).

3. ⚖️ Regulatory & Rubric Drift Explorer

   • Side-by-side comparison of active rubric rules against federal USCDI standards and previous period rulesets.
   • Severity categorization (CRITICAL, HIGH, MEDIUM, LOW) with immediate change management actions.

4. 🛠️ Provider Remediation Sandbox & Code Studio

   • Automated Remediation Memo Generator: Select any failing hospital facility to generate pre-formatted EHR interface correction instructions with exact invalid code strings and target standard RxCUIs or Table 0112 codes.
   • BigQuery Gold SQL Viewer: Syntax-highlighted Gold tier DDL with a one-click copy button.
   • Looker LookML Studio: Formatted .view.lkml and .model.lkml definitions with copy-to-clipboard functionality.
   • Data Extract Toolbar: Direct client-side download buttons for structured JSON and CSV extracts.

---

100% Synthetic Data & HIPAA Zero-PHI Compliance

All sample datasets included in synthetic_data/ are completely synthetic and procedurally generated.

• Contains zero Protected Health Information (PHI) or Personally Identifiable Information (PII).
• Safe for testing, benchmarking, and demonstration across public or private agent environments.

---

Non-Technical User Guide: Using the Skill in a Chat Agent

This skill is designed so that non-technical users (such as Clinical Data Stewards, Quality Directors, P4P Program Managers, and Healthcare Business Analysts) can perform complex clinical audits without writing SQL or Python code.

How to Use the Skill in 3 Simple Steps:

1. Open your agent chat (in Gemini Enterprise App, Antigravity, or your enterprise agent portal).
2. Attach or reference your clinical data (or copy-paste records directly into the chat prompt).
3. Ask your question in plain English (see ready-to-use sample prompts below).

---

Interactive Walkthrough Examples

Example 1: In-Chat Quick Data Reconciliation (Copy & Paste Method)

A user wants to quickly check a batch of 6 patient records without running any external scripts.

Copy-and-Paste Synthetic Data for Chat:

Health Plan Quality Rule:
- Approved HL7 Discharge Disposition Codes: 01 (Home), 02 (Other Hospital), 03 (SNF), 06 (Home Health), 20 (Expired)
- Required Medication Standard: RxNorm (numeric RxCUI)

Records to Audit:
1. Encounter ID: ENC-101 | Hospital: St. Jude | HL7 Disposition: 01 | Med Code: 866514 (Metformin 500mg) | Med System: RxNorm
2. Encounter ID: ENC-102 | Hospital: St. Jude | HL7 Disposition: 06 | Med Code: 316049 (Lisinopril 10mg) | Med System: RxNorm
3. Encounter ID: ENC-103 | Hospital: Pinecrest | HL7 Disposition: 01 | Med Code: HOSP-LOCAL-501 (Metformin) | Med System: Hospital Formulary
4. Encounter ID: ENC-104 | Hospital: Pinecrest | HL7 Disposition: 02 | Med Code: LOCAL_ALBUTEROL_INH | Med System: Local Catalog
5. Encounter ID: ENC-105 | Hospital: Metro Clinic | HL7 Disposition: DISCH HOME | Med Code: 197361 (Atorvastatin 20mg) | Med System: RxNorm
6. Encounter ID: ENC-106 | Hospital: Metro Clinic | HL7 Disposition: [BLANK] | Med Code: CERNER_RX_9918 | Med System: Custom Catalog

User Prompt:

"Please audit these 6 clinical records against our quality rule. Show me the pass/fail score for each hospital, highlight non-standard codes, and explain what corrections are needed."

Expected Agent Response:

"Here is the quality evaluation for the 6 submitted records:

Hospital Name	Total Records	HL7 Disposition Score	C-CDA RxNorm Score	Combined Score	Status	Key Issues Identified
St. Jude	2	100.0% (2/2 valid)	100.0% (2/2 valid)	100.0%	PASS	Clean data. All codes match RxNorm and HL7 0112 standards.
Pinecrest	2	100.0% (2/2 valid)	0.0% (0/2 valid)	50.0%	FAIL	Non-standard medication codes: HOSP-LOCAL-501 and LOCAL_ALBUTEROL_INH. Must map to RxCUIs.
Metro Clinic	2	0.0% (0/2 valid)	50.0% (1/2 valid)	25.0%	FAIL	Unmapped text DISCH HOME (should be 01), 1 missing disposition, and proprietary code CERNER_RX_9918.

Action Plan:

1. Pinecrest Pharmacy Informatics must map local formulary items HOSP-LOCAL-501 -> RxCUI 866514 and LOCAL_ALBUTEROL_INH -> RxCUI 308056.
2. Metro Clinic interface engine must map free-text discharge status to standard Table 0112 two-digit codes."

---

Example 2: Running a Full Monthly Quality Audit & Canvas Dashboard

A user wants to run a complete month-end reconciliation across 120 HL7 messages and 120 C-CDA documents and view the interactive Canvas dashboard.

User Prompt:

"Please run the full January 2026 clinical reconciliation using our dataset in synthetic_data/bronze_silver/ and the rubric in synthetic_data/rulesets/health_plan_alpha_2026_p4p.yaml. Provide an executive summary and generate the interactive Canvas dashboard."

What the Agent Does:

1. Loads the rubric, USCDI specification, and clinical datasets.
2. Evaluates all 240 records across 4 hospital facilities.
3. Formats an executive summary in chat with pass/fail tables and KPI metrics.
4. Generates output scorecards including the interactive Canvas HTML dashboard and Knowledge Graph model in output_scorecards/.

---

Example 3: Investigating Why a Specific Hospital Failed

A quality manager notices a low score for a specific hospital and needs diagnostic details.

User Prompt:

"Why did Pinecrest Memorial Healthcare fail the January quality audit? Give me the exact numbers, their non-compliant medication codes, and draft an email I can send to their clinical informatics director."

Expected Agent Response:

"### Investigation for Pinecrest Memorial Healthcare System (EHR: MEDITECH Expanse)

Performance Summary:

• Total Records Evaluated: 60 (30 HL7 messages, 30 C-CDA medication entries)
• HL7 Discharge Disposition Score: 96.7% (Target: 90.0%) -> PASS
• C-CDA RxNorm Medication Score: 50.0% (Target: 95.0%) -> FAIL
• Combined P4P Score: 73.3% (Target: 85.0%) -> OVERALL FAIL

Root Cause: 15 out of 30 medication entries used internal hospital catalog codes rather than standard RxNorm concept identifiers (RxCUI).

Top Flagged Proprietary Codes:

• MED_CATALOG_4402 (Amlodipine Besylate 5mg In-House) -> Recommended RxCUI: 855332
• LOCAL_ALBUTEROL_INH (Albuterol MDI Hospital Supply) -> Recommended RxCUI: 308056
• INTERNAL_NDC_UNMAPPED (Unmapped Compound Formulation) -> Needs standard RxCUI mapping

Draft Email for Clinical Informatics:

Subject: Action Required: January 2026 P4P Data Quality Remediation - Medication Terminology

Dear Pinecrest Informatics Team,

During our monthly Pay-for-Performance reconciliation, Pinecrest achieved 96.7% compliance on HL7 discharge dispositions. However, C-CDA medication terminology scored 50.0% against the 95.0% standard.

15 records transmitted local catalog codes (e.g., MED_CATALOG_4402, LOCAL_ALBUTEROL_INH) instead of standard RxNorm OID 2.16.840.1.113883.6.88. Please configure your MEDITECH C-CDA outbound mapping table to emit standard RxCUIs to avoid P4P incentive penalties.

Sincerely,
Quality Operations Team"

---

Example 4: Regulatory & Rubric Drift Analysis (Q1 vs Q2 Upgrades)

A payer updates their scoring guidelines and the quality team needs to know what changed.

User Prompt:

"Health Plan Alpha released an updated Q2 rubric in synthetic_data/rulesets/health_plan_alpha_2026_p4p_v2_updated.yaml. Compare it with our active Q1 rubric and check compliance against the USCDI v3 standard in synthetic_data/rulesets/uscdi_v3_spec.json. What changed and what should we update?"

Expected Agent Response:

"### Regulatory & Rubric Drift Analysis Report

Key Modifications Detected:

1. Allowed HL7 Codes Whitelist Expanded: Health plan added Hospice discharge codes 50 (Hospice - home) and 51 (Hospice - medical facility).
2. Stricter RxNorm Threshold: Medication standardization threshold increased from 95.0% to 98.0% (aligned with USCDI v3 requirements).
3. Overall Pass Threshold Raised: Overall P4P pass minimum increased from 85.0% to 88.0%.
4. Federal USCDI Upgrade: Rubric upgraded from USCDI v2 to USCDI v3 (2022 mandate).

Recommended Actions:

• Update BigQuery Gold tier scoring views using the generated SQL migration script.
• Alert partner hospital interface teams that hospice codes 50 and 51 are now recognized as valid."

---

Example 5: BigQuery SQL & Looker Dashboard Generation

A user wants the agent to produce the exact BigQuery SQL views and LookML files for their data engineering team.

User Prompt:

"Generate the BigQuery CREATE OR REPLACE VIEW SQL statement for our Gold tier scoring dataset in GCP project healthcare-dw-prod and create the LookML view file for our Looker dashboard."

Expected Agent Response:

"The BigQuery view DDL and LookML files have been generated:

1. BigQuery Gold View DDL: Saved to output_scorecards/v_gold_clinical_quality_scores.sql
   • Implements CTE-based evaluation for HL7 disposition and C-CDA RxNorm.
   • Includes versioning labels: plan_id: plan_alpha, rubric_version: 1_0, transaction_month: 2026_01.
2. LookML View Definition: Saved to output_scorecards/lookml/clinical_quality_scores.view.lkml
   • Dimensions: facility_id, facility_name, ehr_vendor, p4p_compliance_status, is_passing.
   • Measures: facility_pass_rate, average_p4p_score, average_hl7_disposition_score, average_ccda_rxnorm_score."

---

Quickstart: Running the Python Code

1. Requirements & Prerequisites

• Python 3.9 or higher
• Standard libraries + pyyaml, pandas, pytest

2. Run the End-to-End Demonstration

Execute the full multi-module demonstration using synthetic data:

python3 -m clinical_reconciliation.cli demo

This runs an end-to-end quality scan, calculates P4P scores, checks drift, generates BigQuery DDL, outputs LookML files, and produces the interactive Canvas HTML dashboard in ./output_scorecards/.

3. Run the Automated Unit Tests (Python unittest & pytest)

Run with pytest:

pytest

Or run with Python's built-in unittest:

python3 -m unittest discover tests

---

CLI Command Reference

The skill CLI provides 6 dedicated subcommands:

1. Quality Scan, Scorecard & Canvas Dashboard Compilation (scan)

Scans parsed HL7v2 and C-CDA files against a health plan rubric:

python3 -m clinical_reconciliation.cli scan \
  --rubric synthetic_data/rulesets/health_plan_alpha_2026_p4p.yaml \
  --hl7 synthetic_data/bronze_silver/hl7v2_messages.json \
  --ccda synthetic_data/bronze_silver/ccda_documents.json \
  --uscdi synthetic_data/rulesets/uscdi_v3_spec.json \
  --period 2026-01 \
  --out-dir ./output_scorecards

2. Regulatory & Rubric Drift Analysis (drift)

Compares active rubric against federal standards or previous versions:

python3 -m clinical_reconciliation.cli drift \
  --rubric synthetic_data/rulesets/health_plan_alpha_2026_p4p.yaml \
  --compare-rubric synthetic_data/rulesets/health_plan_alpha_2026_p4p_v2_updated.yaml \
  --uscdi synthetic_data/rulesets/uscdi_v3_spec.json

3. Generate BigQuery SQL & Gold Tier View DDL (generate-sql)

Generates production BigQuery Standard SQL queries and view DDL:

python3 -m clinical_reconciliation.cli generate-sql \
  --rubric synthetic_data/rulesets/health_plan_alpha_2026_p4p.yaml \
  --project-id my-healthcare-dw-prod \
  --dataset-silver clinical_silver \
  --dataset-gold clinical_gold \
  --period 2026-01 \
  --out-file ./output_scorecards/v_gold_clinical_quality_scores.sql

4. Sync Looker Semantic Layer (sync-looker)

Generates LookML view and model files for Looker:

python3 -m clinical_reconciliation.cli sync-looker \
  --rubric synthetic_data/rulesets/health_plan_alpha_2026_p4p.yaml \
  --project-id my-healthcare-dw-prod \
  --dataset-gold clinical_gold \
  --connection bigquery_clinical_dw \
  --period 2026-01 \
  --out-dir ./output_lookml

5. Migrate Legacy Excel VBA Macros (migrate-vba)

Converts legacy VBA macro logic exports into modern declarative YAML rubrics:

python3 -m clinical_reconciliation.cli migrate-vba \
  --legacy-file synthetic_data/rulesets/legacy_vba_ruleset_macro_export.json \
  --out-file ./synthetic_data/rulesets/migrated_rubric.yaml

---

Repository Structure

clinical-data-reconciliation-skill/
├── .gitignore                               # Git ignore configuration
├── LICENSE                                  # Apache License, Version 2.0
├── SKILL.md                                 # Standard Agent Skill definition (root)
├── README.md                                # Project documentation & User Guide
├── requirements.txt                         # Python dependencies
├── pyproject.toml                           # Package configuration
├── assets/
│   └── clinical_reconciliation_architecture.jpg # Modern Architecture and Canvas UI diagram
├── skills/
│   └── clinical-data-reconciliation/
│       └── SKILL.md                         # Discovery path for Antigravity / Agent harnesses
├── clinical_reconciliation/                 # Core Python package
│   ├── __init__.py                          # Package export definitions
│   ├── cli.py                               # CLI entrypoint & subcommands
│   ├── rules/
│   │   ├── models.py                        # Data models (Rubrics, Scores, Drift)
│   │   ├── parser.py                        # Ingestion of YAML, JSON, and VBA rules
│   │   └── drift.py                         # Regulatory & Rubric drift detector
│   ├── engine/
│   │   ├── hl7_evaluator.py                 # HL7v2 PV1-36 evaluation engine
│   │   ├── ccda_evaluator.py                # C-CDA RxNorm auditing engine
│   │   └── reconciler.py                    # Master reconciliation orchestrator
│   ├── bigquery/
│   │   ├── sql_generator.py                 # BigQuery Standard SQL query generator
│   │   ├── view_updater.py                  # BigQuery Gold View DDL generator
│   │   └── version_matrix.py                # Historical version matrix manager
│   └── visualization/
│       ├── canvas_dashboard.py              # Interactive Canvas HTML Dashboard generator
│       ├── knowledge_graph.py               # Clinical Knowledge Graph network builder
│       ├── scorecard.py                     # Multi-format scorecard & report exporter
│       └── looker_sync.py                   # Looker LookML semantic layer sync
├── synthetic_data/                          # 100% Synthetic Non-PHI Datasets
│   ├── bronze_silver/
│   │   ├── hl7v2_messages.json              # Synthetic HL7v2 records (120 msgs)
│   │   ├── hl7v2_messages.csv               # Synthetic HL7v2 records (CSV format)
│   │   ├── ccda_documents.json              # Synthetic C-CDA medication entries (120 entries)
│   │   └── ccda_documents.csv               # Synthetic C-CDA medication entries (CSV format)
│   ├── rulesets/
│   │   ├── health_plan_alpha_2026_p4p.yaml  # Health Plan Alpha Q1 P4P Rubric
│   │   ├── health_plan_alpha_2026_p4p_v2_updated.yaml # Updated Q2 Rubric (with drift)
│   │   ├── health_plan_beta_2026_p4p.yaml   # Health Plan Beta Rubric
│   │   ├── uscdi_v2_spec.json               # Federal USCDI v2 specification
│   │   ├── uscdi_v3_spec.json               # Federal USCDI v3 specification
│   │   └── legacy_vba_ruleset_macro_export.json # Legacy Excel VBA Macro export
│   └── providers_registry.json              # Synthetic hospital facility & EHR registry
├── output_scorecards/                       # Generated outputs and artifacts
│   ├── scorecard_plan-alpha_2026_01.html    # Interactive Canvas HTML executive dashboard
│   ├── scorecard_plan-alpha_2026_01_knowledge_graph.json # Clinical Knowledge Graph model
│   ├── scorecard_plan-alpha_2026_01.md      # Executive summary markdown report
│   ├── scorecard_plan-alpha_2026_01.csv     # Provider-level metric extract (CSV)
│   ├── scorecard_plan-alpha_2026_01.json    # Complete structured evaluation JSON
│   ├── v_gold_clinical_quality_scores.sql   # BigQuery Gold tier view DDL
│   └── lookml/
│       ├── clinical_quality_scores.view.lkml     # LookML View definitions
│       └── clinical_data_reconciliation.model.lkml # LookML Explore and Model
└── tests/                                   # Unit & Integration Test Suite (pytest)
    ├── __init__.py                          # Test package discovery
    ├── test_canvas_and_graph.py             # Tests for Canvas Dashboard & Knowledge Graph
    ├── test_rules_parser.py                 # Tests for Rule Ingestion
    ├── test_evaluators.py                   # Tests for HL7, CCDA & Reconciler
    ├── test_drift_bq_looker.py              # Tests for Drift, BigQuery & Looker
    └── test_cli_and_drift_flagging.py       # Tests for CLI & Source Flagging

---

Supported Clinical Standards & Vocabularies

Standard / Domain	Version / OID	Evaluation Scope
HL7v2 PV1-36	HL7 Table 0112 / UB-04 FL 17	Discharge disposition standard code validation against dynamic plan whitelists
C-CDA Medication Activity	OID 2.16.840.1.113883.6.88	Validates standard RxNorm RxCUIs vs local proprietary hospital codes
USCDI	v2 / v3 / v4 (ONC)	Enforces federal terminology standards and mandatory data classes
P4P Scoring Rubrics	Plan-specific (YAML/JSON)	Weighted domain scoring and provider pass/fail tier calculations
Interactive Canvas UI	HTML5 / CSS3 / Cytoscape.js	Single-page reactive visual dashboard with Knowledge Graph and simulator
Google Cloud BigQuery	Standard SQL	Automated Bronze/Silver validation CTEs and Gold view DDLs
Looker Semantic Layer	LookML	Auto-generated views and explores for direct BigQuery BI dashboards

---

License

This project is open-source software licensed under the Apache License, Version 2.0. For the full license text and conditions, please see the LICENSE file in the root directory of this repository.