Edit rules engine YAML

Outcome

A new or edited rule lives in a draft, dry-run-tested against real entities, submitted for approval, approved, and published — with a clear audit trail and a one-click rollback if something goes wrong.

Prerequisites

Scope	What it lets you do
billing.rules.read	Browse rule sets and versions
billing.rules.write	Save drafts, run dry runs
billing.rules.submit	Submit a draft for approval
billing.rules.approve	Approve / reject a submitted version

A rule set's lifecycle is: DRAFT → SUBMITTED → ACTIVE → ARCHIVED. There is no APPROVED status — approval transitions the version directly to ACTIVE.

What rules govern

The engine runs rules at three points:

Stage	Rule kind	Examples
PRE_SUBMIT_VALIDATE	modifier_validation, auth_required, bundle_check	Block submission if a required modifier is absent.
PRE_SUBMIT_SCRUB	service_line_filter, unit_cap	Drop or downcode lines that exceed payer rules.
POST_REMITTANCE	denial_classifier, appeal_eligibility	Tag a denial as appealable.

Steps

1. Pick Configuration → Rules at /admin/rules. The header has a kind switcher (PRE_SUBMIT_VALIDATE, PRE_SUBMIT_SCRUB, POST_REMITTANCE); pick the kind whose rules you want to edit.

   The list groups rule sets by scope: tenant-wide, per-payer, per-program, etc. Filter by name or scope dimension to narrow it.

2. Click a rule set to open its detail. The Versions panel lists every version of the rule set with its status, the user who created it, and the publish timestamp. The currently ACTIVE version is highlighted; older versions are ARCHIVED.

3. To edit, click + New draft from active (or open an existing DRAFT version). The Monaco YAML editor opens with the published YAML pre-filled.

   The editor enforces the per-kind schema as you type — invalid YAML highlights with a red squiggle and a tooltip explaining what is missing. Cmd/Ctrl + . shows quick-fix suggestions.

4. Define the scope with the Scope picker on the right rail. The 7 dimensions:

   Dimension	Example
   State	OH, MI, or any
   Payer	A specific registered payer, or any
   Program	A specific program, or any
   Contract	A specific contract, or any
   Procedure code	A specific code, or any
   Modifier	A specific modifier, or any
   Service line	professional, institutional, or any

   Most-specific match wins at execution time. The Scope readout under the editor shows the full precedence path so you can predict behavior.

5. Dry-run the draft with the Dry run panel. Set:

   • State and as-of date for the rule context.
   • An entity to evaluate — paste a claim, charge, or denial JSON.

   The panel runs your draft through the engine and displays:

   • Which version of which rule set ran.
   • Each rule's outcome (PASS, FAIL, WARN, SKIP).
   • The precedence path (which rule sets were considered).

   Iterate until the dry-run produces the behavior you want.

6. Save the draft with Save draft. The version stays DRAFT and is private to your edits.

7. Submit for approval with Submit. The version moves to SUBMITTED and appears on the approver's queue.

8. An approver opens the version and reviews the diff (Diff tab — left/right Monaco diff editor of the prior ACTIVE vs the submitted YAML). They click Approve or Reject with reason. Approval transitions the new version to ACTIVE and archives the prior version.

9. Optional rollback: open the prior ARCHIVED version → Restore as draft → Submit / Approve. The platform never destroys old versions.

Validation

Check	Expected
Draft saved	Version appears in the Versions panel as DRAFT.
Dry-run produces expected outcome	Iterate until it matches.
Submission notifies approver	The approver's /admin/rules shows a count badge.
After approval, prior version is ARCHIVED	New active version starts firing on next claim build.

Troubleshooting

Symptom	Cause	Fix
Editor red squiggle says "schema mismatch"	YAML does not match the rule kind's zod schema	Hover for the exact field error; the schema lives in the editor itself.
Dry-run says SKIP	The rule's scope did not match the entity	Adjust scope or test entity.
Approval button greyed out	You hold submit but not approve	Have a teammate with approve review.
Active version does not appear to fire	The engine is using a more-specific scope's rule set	Check the precedence path shown by Dry run.

Next

5.4 — Edit modifier rules