Skip to content

Instantly share code, notes, and snippets.

@diegolinhares
Created December 12, 2025 13:56
Show Gist options
  • Select an option

  • Save diegolinhares/7b1923a97afde5bb243f97c18bd04daf to your computer and use it in GitHub Desktop.

Select an option

Save diegolinhares/7b1923a97afde5bb243f97c18bd04daf to your computer and use it in GitHub Desktop.

Pending Questions - Authorization Benefits

Document for tracking open questions that need clarification from Craig Hospital team Last updated: December 2024


⚠️ Questions Requiring Confirmation

1. Colorado Medicaid - After 48 Units

Context from transcriptions:

Kelsey (08:58): "If it's Colorado Medicaid, it is pretty set that they have a set number of units up front and then it varies after that."

What we know:

  • PT + OT share initial 48 units
  • "It doesn't matter what kind of units" - any CPT counts
  • After 48 units, "it varies"

Questions:

  • What exactly happens after the 48 shared units are exhausted?
    • New authorization with individual limits?
    • Patient pays out-of-pocket?
    • Different rule per patient/plan?
  • Does Speech Therapy (ST) also share the 48 units, or is it just PT + OT?
  • Should the system automatically detect "Colorado Medicaid" or does the funder manually configure the shared bucket?

Current implementation: Funder manually creates a shared benefit group with 48 units for PT/OT.


2. Financial Aid / Medical Aid - Business Logic

Context: Step 3 of the wizard captures PatientAssistanceAmount and WriteOffAmount.

What we have:

  • Storage of amounts in auth_authorization
  • Boolean getters (hasPatientAssistance, hasWriteOff)
  • Display in wizard and review screens

Questions:

  • Does Financial Aid affect any usage calculations?
  • Do we need to track how much of the assistance has been used?
  • Are these values used in any reports or just for informational display?
  • Who updates these values and when? (One-time at authorization or ongoing?)

Current implementation: Informational only - no impact on calculations.


3. Units Per Day Limit (Edge Case #7)

Context from transcriptions:

"Every once in a while there's a units per day limitation is the most common one" "It is in the text box that the funders..." (was free text in Epic)

Questions:

  • How frequently does this edge case occur?
  • Should we add a MaxUnitsPerDay field to benefit_service?
  • If implemented, what should happen when limit is exceeded? (Alert only or block?)

Current implementation: NOT implemented in MVP. Marked as future enhancement.


4. Deductible and Out-of-Pocket Updates

Context: Fields DeductibleMetToDate and OutOfPocketMetToDate in patient_coverage.

What we documented:

"This field is updated MANUALLY by the funder when they receive an EOB (Explanation of Benefits) from insurance."

Questions:

  • Is this the correct workflow? Funder manually updates when EOB arrives?
  • How often are EOBs received? (Monthly? Per claim?)
  • Should there be any validation or audit trail for these updates?

Current implementation: Manual update by funder, no automatic calculation.


5. CPT Code to Department Association

Context from transcriptions:

Isis: "One CPT code can be connected to multiple services. So for example it can be for PT or ST." Sandra: "If we assume it like if we assume that they are for a specific specialty, then it might be an issue."

What we have:

  • cpt_codes table with simple PK (Code)
  • Department association happens via benefit_service_cpt

Questions:

  • When a CPT code like 97535 is used, how do we know if it's for PT or OT?
  • Is this determined by the Epic transaction data (hsp_transactions.departmentId)?
  • Do we need a cpt_code_department mapping table?

Current implementation: We rely on Epic's departmentId in transactions to determine which department used the CPT.


6. Evaluation Codes by Department

Context: We hardcoded evaluation codes in the seed:

const EVALUATION_CODES = new Set([
  // PT: 97161, 97162, 97163, 97164
  // OT: 97165, 97166, 97167, 97168
  // ST: 92521, 92522, 92523, 92524
  // PSY: 90791, 90792, 96130, 96131, 96132, 96133
]);

Questions:

  • Is this list complete and accurate?
  • Do evaluation codes ever change? (CMS annual updates)
  • Should this be configurable by admin instead of hardcoded?

Current implementation: Hardcoded in seed, marked with IsEvaluationCode = true.


7. Multiple Authorizations Overlap

Context: A patient can have multiple authorizations with overlapping date ranges.

Questions:

  • How should the system handle overlapping authorizations for the same service?
  • Should there be a warning when creating an overlapping authorization?
  • For consumption calculations, which authorization takes priority?

Current implementation: No overlap detection. Each authorization calculated independently.


8. Rollover Logic (CPT Cap with Rollover)

Context from transcriptions:

"After 60 units for this specific code are consumed, further charges should roll over to other valid authorizations."

Questions:

  • How does rollover work in practice?
  • Does the system need to automatically find the next valid authorization?
  • What defines a "valid" authorization for rollover? (Date range? Same CPT? Same department?)

Current implementation: NOT implemented. Mentioned as edge case #4 but no automatic rollover logic.


9. Delete Authorization (Soft Delete)

Context from transcriptions:

Deepa (34:15): "It wouldn't be delete expired authorizations, it would be delete authorizations that were entered in error." Sherry (32:42): "We can do virtual deletes. So I think I found a few tables where it was like that, where it was marked as deleted but still in the database."

What we have:

  • Current plan says "No DELETE endpoint"

Questions:

  • Do we need a soft-delete for authorizations entered in error?
  • Who can delete? (Supervisor only, or funders too?)
  • Should there be an audit trail for deletions?

Current implementation: No delete functionality planned.


10. Multiple Insurances per Patient (Primary/Secondary/Tertiary)

Context from transcriptions:

Deepa (17:46): "A lot of our patients have multiple insurances, as it turns out." Sherry (42:36): "What about like a third or fourth insurance? Is it really only primary and secondary?"

What we have:

  • Coverage selection in wizard (via GET /patients/:patientId/coverages)
  • One coverageId per authorization

Questions:

  • Can a patient have authorizations for multiple insurances simultaneously?
  • How do we handle primary vs secondary insurance billing priority?
  • Is there ever tertiary insurance?

Current implementation: One coverage per authorization. Multiple authorizations can exist for different coverages.


11. Billing Method Varies by Service within Same Authorization

Context from transcriptions:

Wendi (19:12): "Sometimes the billing method, all codes are one unit. And sometimes the codes are individually per unit. So it makes it complicated." Wendi (20:03): "If the PT codes are bundled into one unit... But then OT might be bundled individually."

What we have:

  • One billingMethod per authorization

Questions:

  • Can billing method vary by service within the same authorization?
  • Example: PT billed by Units, OT billed by Days in same auth?
  • Should billingMethod be at the benefit_group or benefit_service level instead?

Current implementation: billingMethod is at authorization level (affects all services equally).


12. Specialty Services (Tech Lab, Adaptive Transportation, etc.)

Context from transcriptions:

Heather (38:33): "They might also be going to our tech lab and being seen by speech therapists... And then they could be seen in tech lab... and adaptive transportation..." Heather (32:19): "We have like, specialty services that roll."

Questions:

  • Are tech lab, adaptive transportation, etc. separate departments or sub-departments?
  • How do they map to PT/OT/ST/PSY?
  • Do they need their own department entries?

Current implementation: Only 4 departments (PT, OT, ST, PSY). Specialty services not explicitly handled.


13. Plan Year vs Calendar Year vs Authorization Period

Context from transcriptions:

Deepa (58:57): "The per year is usually the plan year is a calendar year, sometimes not." Heather: "Calendar year, plan year, or specific authorization period."

What we have:

  • startDate and endDate in authorization

Questions:

  • Do we need to track if it's calendar year vs plan year?
  • Should there be a periodType field (CalendarYear, PlanYear, Custom)?
  • For yearly tracking (like deductibles), which year applies?

Current implementation: Just dates, no explicit period type.


14. Re-authorization / Extension Process

Context from transcriptions:

Kelsey (01:01:19): "Once you go through those 20 sessions, you then have to re-basically do another authorization for additional stuff."

Questions:

  • Is there a link between original authorization and re-authorization?
  • Should we track previousAuthorizationId for history?
  • Does remaining balance ever roll over to new authorization?

Current implementation: No link between authorizations. Each is independent.


15. Total Roll-up Display Confusion

Context from transcriptions:

Heather (23:16): "I'm concerned they'll get confused by a total number when what they have to be tracking by is individual unit totals." Heather (22:44): "We didn't have a total roll up in our old tracker because therapists have to track it by individual count."

Questions:

  • Should the insights modal show a "total" or only individual counts?
  • Is aggregating to a total confusing for therapists?
  • What do funders need vs what therapists need?

Current implementation: Phase 3 shows individual consumption records. No "grand total" across all benefits.


✅ Questions Already Answered

# Question Answer Source
1 Is coverage stored? Yes, via CoverageId FK to Epic coverage table Entity review
2 How are unlimited benefits represented? IsUnlimited = true flag (replaced old "5000" placeholder) Transcription 20250930
3 Do evaluations always count? Configurable via EvaluationCounts boolean per authorization Transcription 20250930
4 Same CPT for different departments? Simple PK, department determined by transaction data Investigation + transcription

📊 Summary Statistics

┌─────────────────────────────────────────────────────────────┐
│                    PENDING QUESTIONS SUMMARY                 │
├─────────────────────────────────────────────────────────────┤
│  Total Open Questions:    15                                 │
│  🔴 High Priority:         3                                 │
│  🟡 Medium Priority:       8                                 │
│  🟢 Low Priority:          4                                 │
│                                                              │
│  Already Answered:         4                                 │
└─────────────────────────────────────────────────────────────┘

📋 Action Items

Priority # Question Action Assignee
🔴 High 1 Colorado Medicaid post-48 Ask Kelsey/Deepa what happens after 48 units Craig Team
🔴 High 11 Billing method varies by service Can PT be Units while OT is Days in same auth? Craig Team
🔴 High 9 Delete authorization Do we need soft-delete for errors? Craig Team
🟡 Medium 2 Financial Aid logic Confirm informational only Heather
🟡 Medium 4 Deductible updates Confirm manual update workflow Wendy
🟡 Medium 5 CPT to Department Confirm Epic determines department Sherry
🟡 Medium 10 Multiple insurances Clarify primary/secondary handling Deepa
🟡 Medium 12 Specialty services How do tech lab, etc. map to departments? Heather
🟡 Medium 13 Plan year vs calendar year Need a period type field? Deepa
🟡 Medium 14 Re-authorization Link to previous auth? Kelsey
🟡 Medium 15 Total roll-up Confirm individual counts only Heather
🟢 Low 3 Units per day limit Document as future enhancement N/A
🟢 Low 6 Evaluation codes Confirm list is complete Kelsey
🟢 Low 7 Overlapping auths Determine if warning needed N/A
🟢 Low 8 Rollover logic Determine if automatic or manual N/A

🚨 Critical Decisions Needed Before Implementation

Must Resolve Before Phase 1 (Database)

  • #9 Delete Authorization - Affects table structure (soft delete flag)
  • #11 Billing Method per Service - Affects where billingMethod lives

Must Resolve Before Phase 2 (API)

  • #1 Colorado Medicaid - May need special handling in wizard

Must Resolve Before Phase 3 (Calculations)

  • #15 Total Roll-up - Affects insights display

Document maintained as part of the Benefit Tracking Logic epic Add new questions as they arise during implementation Last updated: December 2024

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment