A judgment engine on the MediRegs regulatory corpus — claims checked pre-bill, denials defended with version-proof citations, audit exposure mapped from public data.
WK Code Games Q1 entry. Clean-room prototype: public CMS sources only, synthetic fixtures, no PHI.
Live demo: https://advocate-owlguardcos-projects.vercel.app
Run it yourself: cp .env.example .env && docker compose up — see PORTING.md for the path from this demo to production infrastructure.
Master Suite is where a hospital goes to look something up. Advocate does the looking up automatically — for every claim, under the rule in effect on the date it was billed, with a citation on every output.
Ten surfaces covering seven of the ten revenue cycle stages.
| Surface | Stage | What it replaces |
|---|---|---|
| Code Check | ④ Coding | Detects CPT/HCPCS/ICD-10/ICD-9/NDC, runs device C-code crosswalk, modifier advisor, MUE, LCD supporting diagnoses, NDC-to-J-code, GEMs legacy map, and deleted-code replacement — one call, everything out. |
| Claim Battery | ④ Coding | Upload a CSV of claims. Ten deterministic checks per line: NCCI PTP, MUE, LCD/NCD coverage, device crosswalk, prior auth, OPPS comprehensive bundling, enrollment (PECOS), exclusion (OIG LEIE), expected payment, 90-day change flag. Every flag returns a citation, suggested fix, and dollars at risk. |
| Pre-Bill Checklist | ⑤ Scrubbing | MUE, device, prior auth, CDM revenue code, and CARC denial prediction — before a claim touches the clearinghouse. |
| Prior Auth / WISeR | ① Pre-service | CMS OPD PA program + UHC/Aetna lists. WISeR flag: claims from the six 2026 pilot states (AZ/NJ/OH/OK/TX/WA) billing a WISeR Appendix A code are flagged to confirm AI-screened prior auth is on file. |
| Denial Explainer | ⑧ Remittance | Paste denial codes or raw remittance text. Returns plain-English explanation and action guidance for 37 curated high-frequency codes (24 CARC + 13 RARC), auto-extracted from free text. |
| Appeal Defense | ⑦⑨ Denial mgmt | Reads a denial letter, pulls the regulatory text in force on the date of service, flags CITED_VERSION_SUPERSEDED when the payer cited old policy, drafts the redetermination with a real Appeals Council precedent. |
| Change Attestation | All | Every regulatory change surfaced by the battery is logged automatically. Acknowledging it requires a named person — written permanently before it counts as seen. Board report breaks out changes by source (CMS / MAC / state) and tracks outstanding vs. acknowledged. |
| Protected-$ Ledger | ⑤ Scrubbing | Running total of dollars flagged pre-submission, still blocked, and overridden — each override requiring a named approver and written reason on a permanent audit trail. |
| Exposure Map | ⑩ Audit | Type a hospital name — total Medicare dollars, subset in active audit crosshairs (RAC, OIG, TPE, WISeR), PEPPER outlier flags, Hospital Compare quality, specific codes at risk. |
| Ask Advocate | All | Tier-1 deterministic for device/code questions, tier-2 grounded synthesis with citation injection, tier-3 honest abstain. Cites or shuts up. |
Also shipped and reachable in the UI, one layer down: CDM Validator (③ charge capture), CDI Assistant (② clinical encounter), and the Remittance Decoder (⑧, broader 78 CARC + 58 RARC lookup behind the Denial Explainer's curated set).
The archives. Version-proof appeals require the exact text in force on the date of service. CMS does not archive its own content. No competitor does. WK does, back to 1967. Every MAC and four of five RACs run on MediRegs. The auditors' own source of truth, pointed the other way.
The NCCI depth. The only tool covering Medicare AND Medicaid, hospital AND physician edits.
The neutrality. WK has no payer, no RCM outsourcing arm, no EHR. The largest competitor is owned by a payer. It cannot build appeal defense against its own parent.
The API seam. ADVOCATE_PROVIDER=mediregs swaps the public-CMS-data backend for real MediRegs Analytical API content. One environment variable, no code change. The architecture is built for this transition.
WISeR. CMS launched its AI pre-payment review model January 1, 2026 in six states. AI vendors screen claims before payment and earn up to 20% of what they deny. Advocate flags every WISeR-exposed claim before it hits that screen.
The gold card. Providers who consistently pass WISeR screening are exempted from it. Advocate's pre-bill checks build the clean submission history that earns exemption — not just defense against denials, but the path out of the review process that causes them.
The numbers. 80.7% of appealed MA denials overturned when filed (KFF 2026), but 11.5% are ever appealed. $118 cost per appeal; most hospitals write off the rest. 418 CPT + 160 HCPCS changes January 1, 2026 — every deleted code without a replacement is a denial stream. $5.7B FCA healthcare settlements FY2025.
corpus/ Versioned regulatory content. Effective-date resolution
is the core primitive. Citation on every output.
advocate/
battery.py Deterministic rules engine (10 checks). Provider seam.
crosswalk.py Unified crosswalk: CPT/HCPCS/ICD-10/ICD-9/NDC detected and routed.
carc_rarc.py CARC/RARC denial-code explainer (37 curated codes, public WPC/MAC data).
ingest_carc.py Broader CARC/RARC lookup table (78+58) behind the remittance decoder.
change_log.py Regulatory-change attestation trail. Named approver required.
review.py Submit rail state machine + override audit trail + protected-$ ledger.
providers/ local (public CMS data) and mediregs (Analytical API) backends.
Parity tests assert identical output. ADVOCATE_PROVIDER switches.
letters.py Denial letter parser + version check (fully deterministic).
appeal.py Appeal drafter. Cite-or-abstain enforced.
exposure.py Exposure Map: CMS utilization + audit targets + PEPPER + quality.
assistant.py Ask Advocate. Tier-1 deterministic, tier-2 grounded, tier-3 abstain.
clearinghouse.py Availity sandbox client. ProductionGuard blocks non-sandbox calls.
llm.py Single chokepoint for all model calls. Citation stripper enforced.
web/app.py FastAPI on :8020.
web/static/ Single-page shell. No framework, no build step.
ProductionGuard: clearinghouse.py will not fire against a live payer without ADVOCATE_ENV=sandbox. Cannot be bypassed by config.
Cite-or-abstain: All LLM output passes a citation stripper. Any citation not in the deterministic payload is removed and the response stamped REVIEW REQUIRED.
The ten checks battery.run() applies to every claim line:
| Check | Source |
|---|---|
| NCCI PTP pair | CMS quarterly edits — modifier-indicator logic included |
| MUE units | CMS quarterly |
| LCD/NCD coverage | MediRegs regulatory content — effective-date versioned |
| Device-code crosswalk | CMS IOCE + OPPS Addendum B |
| Payer PA requirement | CMS OPD PA program + UHC/Aetna lists |
| OPPS comprehensive bundling | CMS OPPS Addendum B — status indicators N, J1, Q1/Q2/Q3 |
| Enrollment + exclusion screening | PECOS Order & Referring, OIG LEIE |
| Expected payment | OPPS Addendum B, PFS RVU — national unadjusted, labeled |
| Recent change flag | HCPCS quarterly, ICD-10 addenda — 90-day lookback |
| WISeR prior-auth risk | CMS WISeR Appendix A — pilot-state advisory |
Hospital Compare quality (CMS Provider Data Catalog) is a facility-level signal surfaced by the Exposure Map, not a per-line battery check.
git clone https://github.com/owlguardco/codegames
cd codegames
cp .env.example .env
docker compose up # first run builds the corpus, ~5-10 min
# http://localhost:8020Without Docker:
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m corpus.cli ingest-all # ~6 min, ~500MB
uvicorn web.app:app --port 8020pytest # 112 passed, 2 skipped (live credentials required for skipped)export ADVOCATE_PROVIDER=mediregs
export MEDIREGS_API_BASE=https://api.mediregs.example.com
export MEDIREGS_API_KEY=your_key_hereadvocate/providers/mediregs.py has typed stubs for all API methods marked TODO(connect-trial). Every method raises KeysUnavailable without credentials. Trial keys: Connect portal at dw.wolterskluwer.com.
Frontend (Vercel): https://advocate-owlguardcos-projects.vercel.app Backend (Railway): https://advocate-production-136d.up.railway.app
These are demo hosting only — not a statement about production infrastructure. See PORTING.md for what a real deploy target looks like and what it would take to get there, and deploy/README.md for how the current demo is wired.
| Gap | What closes it |
|---|---|
| MediRegs API keys | ADVOCATE_PROVIDER=mediregs + Connect portal trial |
| ASA anesthesia crosswalk | MediRegs ASA content via API keys |
| MS-DRG grouper | MediRegs Analytical API |
| CPT descriptors | MediRegs regulatory content (AMA licensed) |
| PHI / real patient data | WK covered-entity infrastructure + BAA |
| EHR integration (Epic FHIR / CDS Hooks) | Production gate-2 roadmap |
| Override dollar-threshold / second-approver policy | Policy decision (see PORTING.md Phase 3) |
| Full WPC CARC/RARC list | WPC feed or tri-annual ingest — the Denial Explainer's curated set covers the 37 highest-frequency codes; the remittance decoder's lookup covers 136 |