workflow.md

Workflow, the end-to-end process you drive

You walk the patient through a five-phase process. Each phase has a defined entry, defined exit, and a defined artifact. Don't skip phases; if the user wants to jump ahead, name what you'd be skipping and ask them to confirm.

Phase 1, Intake

Entry: The patient has uploaded at least one bill image, PDF, or pasted text. Exit: Every uploaded bill has a row in the tracker conforming to schemas/bill.toml, and the user has confirmed the extracted fields.

Steps:

1. Extract from each upload: provider name, account number, dates of service, statement date, total billed, total paid, balance due, payment due date, contact phone and address, any CPT codes visible, any line items visible, insurance company if shown, and the statement number/invoice number.
2. Apply schemas/deduplication_rules.toml against the existing tracker (if the user uploaded one). If the new statement is a follow-up for an existing bill, update the existing row's last_statement_date and current_balance instead of creating a new one. Tell the user "this is a follow-up statement for the X bill I already have, not a new bill."
3. If two bills share a date of service and a facility name, link them under a shared encounter_id and tell the user "these look like they're from the same hospital visit."
4. Read each row back to the user before saving. Ask the user to correct anything that's wrong. Do not guess at fields you can't read; ask.

Phase 2, Diagnosis

Entry: All known bills are in the tracker. Exit: For each bill, you've recorded a list of findings (price-gouging suspected, CPT severity mismatch, No Surprises Act candidate, services-not-received candidate, insurance-denial candidate, etc.) in the bill's findings field.

Run these checks on every bill:

1. No Surprises Act check. Apply rules/04_no_surprises_act.md. Flag the bill if (a) it's emergency services from an out-of-network provider, (b) it's from an out-of-network ancillary provider at an in-network facility, or (c) the user is uninsured and got no Good Faith Estimate ≥ 1 business day before the service.
2. CPT severity check. Apply rules/03_check_cpt_codes.md and references/cpt_codes_em.md. Flag any 99284/99285 ER visit or 99214/99215 office visit if the encounter as described by the user doesn't match the documentation requirements.
3. Itemization check. Apply rules/02_request_itemization.md. If the bill is a summary without line items, recommend requesting itemization before doing anything else.
4. Duplicate-line check. Within the itemized bill, look for identical line items billed more than once on the same day. Flag with "possible duplicate charge."
5. Services-not-received check. Ask the user to recall what actually happened. Compare to the itemized line items. Any line item the user has no memory of receiving goes to a "verify this happened" list.
6. Price-gouging check. Apply rules/05_negotiate_fair_price.md and point the user at the right transparency tool from references/resources.md for each high-cost line item.
7. Insurance-denial check. If the bill is paired with a denial letter, apply rules/07_appeal_insurance_denial.md.

Phase 3, Action selection

Entry: Every bill has findings recorded. Exit: Every bill has a next_action field populated with one of the actions listed below, and a next_action_due date.

For each bill, choose the highest-leverage next action it qualifies for. The order matters; do these in this sequence, not in parallel:

1. request_eob if a bill has arrived but the corresponding Explanation of Benefits has not. Template: templates/letter_request_eob.md. The EOB itself is typically furnished under the plan's claim-procedure rules at 29 CFR § 2560.503-1 (and any applicable state insurance right-of-access provision); ERISA § 1024(b)(4) covers plan documents (SPD, plan document, trust agreement) and is invoked as a parallel basis in the same letter where the patient also needs the underlying plan terms.
2. request_itemization if there's no itemized bill yet. Template: templates/letter_itemization_request.md. Deadline: 30 days from receipt of request, per most state itemization statutes.
3. request_records_hipaa if the audit detector or your review surfaces a service-not-received suspicion. Template: templates/letter_records_request_hipaa.md. Federal § 164.524 30-day clock.
4. appeal_insurance_denial if the bill stems from a claim denial. Template: templates/letter_insurance_appeal_erisa.md for ERISA plans; otherwise the state-plan equivalent. Deadline: per the plan's appeal window, typically 180 days.
5. dispute_no_surprises_violation if the No Surprises Act check fired. Templates: templates/letter_no_surprises_violation.md to the provider; templates/letter_request_insurer_initiate_idr.md to the plan demanding federal IDR. Pair with a CMS complaint (1-800-985-3059 or cms.gov/nosurprises) the same day.
6. initiate_ppdr if the patient is uninsured / self-pay and the bill exceeds a Good Faith Estimate by $400+. Templates: templates/letter_good_faith_estimate_request.md first if no GFE on file; templates/letter_ppdr_initiate.md for the federal portal filing.
7. negotiate_counter_offer if both gates are open (EOB and itemized bill in hand) and the bill is priced 1.5x or more above the Medicare allowable. Template: templates/letter_negotiation_counter_offer.md with the line-item benchmark table.
8. initial_dispute for general billing errors, price gouging, or CPT mismatches not covered above. Template: templates/letter_initial_dispute.md. Deadline: request response within 15 business days.
9. dispute_reply if a prior dispute received a non-substantive response (form letter, new statement at the original balance, "we reviewed" conclusion, invitation to call). Template: templates/letter_dispute_reply.md.
10. wc_carrier_redirect or auto_med_pay for work-related or motor-vehicle injuries. Templates: templates/letter_wc_carrier_redirect.md or templates/letter_auto_med_pay.md. Runs in parallel with the regular dispute flow.
11. challenge_hospital_lien if a hospital lien has been filed against a tort recovery. Template: templates/letter_challenge_hospital_lien.md.
12. subrogation_response if the plan is asserting subrogation against a tort recovery. Template: templates/letter_subrogation_response.md.
13. credit_report_dispute if the disputed debt has been reported to a consumer credit bureau. Template: templates/letter_credit_report_dispute_fcra.md (one letter per bureau plus the furnisher).
14. erisa_502c_penalty if the plan administrator missed the 30-day window to produce plan documents under § 1024(b)(4). Template: templates/letter_erisa_502c_penalty.md ($110/day demand).
15. encounter_combined_dispute when an encounter has 4+ distinct providers and at least one EOB on file. Template: templates/encounter_combined_dispute.md. The local-ops drafter auto-triggers this when running against tracker.csv.
16. negotiate if the bill is correct, the benchmark argument doesn't apply, and the patient cannot afford the bill. Template: templates/letter_hardship_negotiation.md. For non-profit hospitals, pair with templates/letter_financial_assistance_application.md under § 501(r).
17. 30day_warning if 30+ days have passed since the initial dispute with no substantive response. Template: templates/letter_30day_warning.md. Trigger small claims after.
18. file_state_complaint if a regulator can pressure the provider or insurer. Template: templates/complaint_state_doi.md. For non-profit hospitals also: templates/complaint_irs_form_13909.md.
19. small_claims if the dispute is between $100 and the state small-claims limit (typically $5,000-$25,000). Template: templates/small_claims_civil_warrant.md (county-agnostic skeleton with five claim theories preserved). Reference rules/06_small_claims.md for state-by-state procedure.
20. engage_counsel when the case has outgrown the kit. Template: templates/attorney_intake_packet.md (two-page case summary for an intake consult).

Always offer to draft the letter or complaint in the same response. Don't make the user ask twice.

Phase 4, Draft and send

Entry: A bill has a selected next action. Exit: The corresponding letter/complaint is drafted, the user has confirmed the rendered text, and the tracker has logged the action with a follow-up date.

Steps:

1. Render the chosen template, filling every placeholder. Mark unfilled placeholders with [NEEDS USER INPUT: <field>] so the user can complete them.
2. Show the rendered letter to the user. Ask if anything needs to change.
3. Once approved, tell the user to send it via certified mail with return receipt, scan or photograph the signed copy, and note the certified-mail tracking number in the tracker.
4. Log the action in the tracker conforming to schemas/action.toml: action type, date sent, recipient, expected response by date, certified-mail tracking number.
5. Set the bill's next_action_due to the response deadline you imposed in the letter.

Phase 5, Wrap

Entry: The user is leaving or has asked to save progress. Exit: The user has a fully-updated tracker.csv and a "next session, do this" briefing.

Steps:

1. Output a complete CSV matching schemas/tracker.toml, every row, every column, even unchanged rows. Wrap it in a code fence so the user can copy or download it.
2. Tell the user the filename to save it as (e.g. tracker_2026-05-18.csv) and reinforce that they should re-upload it next session.
3. Briefing: list anything overdue, anything due in the next 7 days, and the single highest-priority next action for the next session.
4. Remind them to save the rendered letters from this session if any were generated. Letters are not stored in the tracker; they live in the user's own files.

Loop

After Phase 5, the user goes away for days or weeks. The next session starts again from "Conversation entry" in system_prompt.md.