Manual auto-correction trigger
Outcome
A specific denial gets re-run through the auto-correction engine after upstream context (config rules, auth, duplicate reconciliation) changed.
Prerequisites
denials.updatescope on the JWT.- Familiarity with auto-correction handler coverage.
When to use
| Situation | Use manual trigger? |
|---|---|
| Denial CARC has a registered handler but the engine ran before the prerequisite data was available | Yes |
| Configuration change (modifier rules, payer config, fee schedule) means a previously-FAILED attempt is now expected to succeed | Yes |
Backlog cleanup: re-run a specific cohort without re-firing claim.denied events | Yes (one denial at a time — bulk CLI is a tracked follow-up) |
| Force-retry a previously SUCCESS attempt | No — correct the source data and let the next claim.denied event drive a fresh denial |
Workflow
Open the denial detail page → Corrections tab.
Inspect the Auto-Correction Engine panel. Each pill shows a registered handler that matches the denial's CARC codes. Each pill links to the handler that would run + its supported CARCs.
Read the prior-attempt banner (if present). It shows the most recent SUCCESS / PENDING / FAILED outcome and the rebilled-claim id where applicable.
Click Apply auto-correction (or Re-run with the Force retry checkbox).
Open the History drawer to inspect every
billing.auto_correction_attemptrow (SUCCESS / FAILED / SKIPPED / PENDING) with handler details JSON, failure reason, and rebilled-claim id.
Idempotency contract
billing.auto_correction_attempt carries a partial-unique index on
(denial_id, handler_name) WHERE status <> 'FAILED'.
| Scenario | Behavior |
|---|---|
| Handler already SUCCESS / PENDING / SKIPPED | Cannot insert another non-FAILED row |
Engine called with skipCompleted: true (default) | Short-circuits to SKIPPED in memory; no row inserted |
Engine called with forceRetry: true | skipCompleted flips off; handler invoked again. If SUCCESS would re-insert, the unique index rejects — a sign the data is already corrected |
| FAILED rows | Not unique — re-running a FAILED handler is always allowed |
Reading the success-rate dashboard panel
The dashboard panel (gated on reports.read.{operational|financial})
reads billing.v_auto_correction_success_rate. Bars stack
SUCCESS / FAILED / SKIPPED per CARC. Header KPIs:
- Overall —
SUM(successes) / SUM(attempts) - Recovered —
SUM(recovered_amount_cents) - Attempts —
SUM(attempts)
A CARC with sustained low success rate (< 50% over a 30-day window)
typically points to a stale handler (payer changed denial reason coding),
an upstream config gap (no modifier injection rule for a new procedure
code), or a payer-side adjudication change requiring a new handler. Open
apps/rcm-core/src/modules/denial/handlers/ to inspect handler logic
before declaring a config change.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
409 NO_ELIGIBLE_HANDLER | Denial CARC overlaps no registered handler | Either the CARC isn't supported (write off / appeal manually) or a new handler is needed. |
200 with anySuccess: false and SKIPPED outcome | Prior non-FAILED attempt blocks the engine | Confirm via History drawer the prior outcome was SUCCESS — data is already corrected. |
| 200 with FAILED attempt | Handler ran but errored | Read failure_reason in History; fix upstream input then re-run (FAILED → fresh attempt allowed). |
500 from /execute after forceRetry: true on a SUCCESS row | Unique-index violation — engine tried to insert a second SUCCESS | Source data is already corrected; let the next claim.denied event drive a new denial. |
Validation
| Check | Expected |
|---|---|
New auto_correction_attempt row | Inserted with the right outcome |
claim.rebilled event | Fires on SUCCESS w/ rebilledClaimId |
| Dashboard panel | Reflects the new attempt within refresh window |
Follow-ups (not yet shipped)
- A bulk "apply to all matching denials" CLI / route for backlog remediation.
- A dry-run preview that returns the projected corrected-claim diff (CLM05-3 frequency 7, REF*F8 with original PCN, modifier list) without running the handler.
Cross-references
- Auto-correction operator playbook for the engine's full handler registry and idempotency model.
- Denials and appeals for upstream denial workflow.