Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

ADR-015: PM Refund / Recoupment / Takeback Path — Lite-First with PM-53 Umbrella

​

Context

• PM-53-refund-recoupment-takeback-management.md — FULL spec (umbrella)
• PM-09-EN-11-refund-workflow.md — LITE (patient overpayment refunds)
• PM-09-EN-15-payer-overpayment-takeback.md — LITE (payer-side 835 takebacks / overpayments)

• FA consumes a payment_refund_issued event on the cash-receipts side (fa-consume-pm-payment-events Edge Function, per IG-2).
• PM-44 (Automated ERA Reconciliation) detects payer takebacks in incoming 835s and is the upstream signal for PM-09-EN-15.
• PM-26 (Audit Trail) must capture every refund/takeback transition for HIPAA §164.316(b) retention.

1. Measurable revenue protection in 1–2 sprints (HFMA cites 3–7% net revenue at risk from underpayments + improperly handled takebacks).
2. A coherent state machine across patient refunds and payer takebacks (so the same pm_refunds lifecycle handles both sources).
3. A single point where the FA event is published (avoid two competing event contracts).

​

Options Considered

​

Option A: Ship PM-53 as a single FULL spec; mark both lites Cancelled

• How it works: PM-53 alone covers the unified state machine, both data flows, and the FA event contract. Lites archived as 🗂️ Cancelled — superseded by PM-53.
• Pros: Cleanest single-spec narrative; one PR for the umbrella.
• Cons: Slower to ship (full FULL-template scope is 4–6 sprints). Defers measurable revenue protection. PR-review surface is large; reviewer fatigue likely.
• Why not chosen: Time-to-revenue-protection matters; HFMA gap is real today.

​

Option B: Ship two LITE specs (PM-09-EN-11, PM-09-EN-15) as independent deliverables; archive PM-53

• How it works: Each lite ships its own table + state machine + FA event independently. PM-53 archived.
• Pros: Two parallel teams; fastest to MVP.
• Cons: Duplicate state-machine code; two competing FA event payloads (payment_refund_issued from EN-11 vs. payer_takeback_received from EN-15) — FA consumer would need to handle both, which contradicts the “one event per business fact” principle from EVENT_CONTRACTS.md. Risks divergence on pm_refunds table schema if both lites independently model it.
• Why not chosen: Cross-core event proliferation + table-design divergence is exactly the problem the umbrella was meant to solve.

​

Option C: Adopt PM-53 as the umbrella plan; ship the two lites as Phase A and Phase B inside the umbrella ✓

• How it works:
  • PM-53 status → 🗂️ Umbrella plan (not 📋 Specification). Its scope section lists Phase A and Phase B; it defines the unified pm_refunds table, the state machine, and the single payment_refund_issued FA event contract.
  • PM-09-EN-11 (Phase A) implements patient-overpayment refunds against the PM-53-defined pm_refunds table. Target: 2026-Q3.
  • PM-09-EN-15 (Phase B) extends the same pm_refunds table with the payer_takeback source enum value and adds 835 takeback ingest. Target: 2026-Q4.
  • The FA event publisher lives in a shared hook (useIssueRefund) that both lites consume.
• Pros: Time-to-revenue-protection in 1 sprint (Phase A); shared schema and event contract by design; reviewer surface stays small per PR; PM-53 acts as the architectural reference for both Phase implementers.
• Cons: PM-53 scope section needs careful editing to make clear it is “umbrella plan” not “implementation spec”; risk of Phase B drifting from PM-53’s contract if reviewers are not vigilant.
• Why chosen: Best balance of time-to-value, cross-core event-contract hygiene, and reviewer-load distribution.

​

Decision

​

Concrete actions

1. PM-53 spec edits (Wave 0 follow-up):
   • Header status: 📋 Specification → 🗂️ Umbrella plan
   • Add prominent block: “This is an architectural umbrella. The actual implementation lives in PM-09-EN-11 (Phase A) and PM-09-EN-15 (Phase B). PM-53 owns the unified state machine, the pm_refunds table contract, and the payment_refund_issued FA event.”
   • Move generate-tasks references out of PM-53; re-target to the two lites.
2. PM-09-EN-11 spec edits:
   • Add “Phase A of PM-53 umbrella” reference in header.
   • Constrain DDL to the columns required for patient-overpayment source.
   • Use the pm_refunds.source enum value 'patient_overpayment'.
3. PM-09-EN-15 spec edits:
   • Add “Phase B of PM-53 umbrella” reference in header.
   • Constrain DDL to ALTER (add columns if needed) — must not redefine pm_refunds.
   • Use the pm_refunds.source enum value 'payer_takeback'.
4. FA-side coordination:
   • Confirm FA owner accepts the unified payment_refund_issued event payload (with source discriminator field) before Phase A generate-tasks.
   • Add row to docs/architecture/integrations/EVENT_CONTRACTS.md for the unified event.
5. PR sequencing:
   • PR-1: PM-53 header + scope edits (this ADR + Wave 0 commit).
   • PR-2: PM-09-EN-11 spec-review → generate-tasks.
   • PR-3: PM-09-EN-15 spec-review → generate-tasks (after Phase A ships).

​

Consequences

​

Positive

• Phase A revenue protection in 1 sprint.
• Single FA event contract; FA consumer Edge Function written once.
• Unified state machine reduces future maintenance.
• PR-review load distributed across 3 reviewable PRs instead of one mega-PR.
• PM-53 remains the architectural reference document.

​

Negative

• Three artifacts (PM-53 + 2 lites) must stay in sync; risk of drift if Phase B reviewer doesn’t cross-check PM-53.
• “Umbrella plan” is a non-standard status — must be documented in SPEC_GUIDE.md as a recognised type.
• Adds one extra spec-review pass (PM-53 itself, even though no implementation comes from it).

​

Neutral

• PM-37 (Self-Pay AR Ledger) remains adjacent — it consumes the pm_refunds rows for patient-account display but does not own the lifecycle.

​

Compliance

• Constitution §1.1 (PF-only dependency): Umbrella → 2 lites pattern stays within PM core; FA event contract stays within the canonical Platform Integration Layer per ADR-002.
• Constitution §5.2.7 (cross-core FK): No new cross-core FK introduced; pm_refunds.original_payment_id references pm_payments.id (intra-core).
• HIPAA §164.316(b): PM-26 audit captures every pm_refunds state transition (already in scope per existing PM-26 patterns).

​

Related

• specs/pm/specs/PM-53-refund-recoupment-takeback-management.md
• specs/pm/specs/PM-09-EN-11-refund-workflow.md
• specs/pm/specs/PM-09-EN-15-payer-overpayment-takeback.md
• specs/pm/IMPLEMENTATION_LOG.md Decision Log 2026-04-20
• specs/pm/plans/PM-SPEC-AUTHORING-PLAN-20260419.md Wave 0 W0-4
• specs/pm/reports/pm-deep-review-20260419.md Cluster D-1
• docs/architecture/decisions/ADR-002-cl-pm-cross-core-foreign-keys.md (cross-core FK precedent)

​

Review