2.7 Modifier injection rules and payer-scoped overrides

Outcome

Claim scrubbing knows how to inject required modifiers (HO, HQ, GT, U-mods, etc.) for each payer + program + service-line combination the customer bills.

Prerequisites

• 2.6 Payers and programs complete.

Why modifier rules matter

Most state Medicaid plans require service-line modifiers (e.g. HO for master's-level clinician, HQ for group). The platform ships with a curated master rule set; per-tenant overrides handle edge cases.

Steps

1. Confirm the master rule set covers the customer's payers

   Impersonate the tenant → Admin → Rules → Modifier rules → Filter by payer.

   For each payer in the customer's panel, you should see active master rules with the modifier they need. If a rule is missing, decide:

   • All tenants need it: edit the master rule (platform-side action; requires PLATFORM_ADMIN).
   • Only this customer needs it: create a tenant override (next step).

2. Create tenant-scoped overrides for unusual contractual quirks

   Admin → Rules → Modifier rules → Add tenant rule

   Field	Example
   Scope	payer_id = Anthem OH, state = OH, procedure_code IN (90834, 90837)
   Modifier	U7
   Trigger	if program_config.code = 'OH_MEDICAID_FFS'
   Action	INJECT (or WARN, BLOCK)
   Effective	2026-01-01 — open
   Notes	"Per Acme's renegotiated contract clause 4.3"

3. Use the rule editor's dry-run to validate

   The Rules editor has a built-in dry-run panel: paste a sample claim → see what the rule engine would do. The output shows fired rules, modifiers added, and any warnings.

   For YAML rule sets (full custom rules), draft → submit → approve → activate per the lifecycle workflow (mining target — OPERATIONS_RUNBOOK.md §5).

4. Configure group-billing rate adjustments (if applicable)

   For customers billing group therapy (90853, H0035 HQ, etc.):

   Admin → Rules → Group session triggers → Add rule

   Field	Example
   Group size	8
   Procedure	90853
   Rate adjustment	50% per attendee (the master rule already implements PER_ATTENDEE)

   This is mostly read-only inheritance from master rules; only override if the customer's contract differs.

5. Verify supervision rules (for Medicaid plans requiring rendering-vs-supervising NPI)

   Admin → Rules → Supervision rules. Master ships with the canonical CMS supervision rules; review for the customer's payer panel.

Validation

Check	Expected
Tenant-scoped overrides count	matches step 2 inputs
Dry-run on a sample claim	fires the right rules
rules_engine.audit_log (post-activation)	shows the rule activations

Troubleshooting

Symptom	Likely cause	Fix
Rule doesn't fire on dry-run	Scope too narrow	Widen scope (e.g. drop the state filter to test).
Conflict between master and tenant rule	Both inject the same modifier	Tenant overrides win — confirm precedence in the dry-run output.
Effective dates don't match	Off-by-one TZ issue	Use UTC start-of-day timestamps.

Next

2.8 — Ingestion