This is the user-value master for medbill-dispute-kit, the personas and stories that sit above BUILD_PLAN.md and define who the kit serves and what outcomes they need. Stories use Connextra form with Given/When/Then acceptance criteria. Status legend: proposed · accepted · next · priority · shipped (vX.Y.Z) · withdrawn.
- Patient under bills: A US adult who has received one or more medical bills they suspect are wrong or unfair. May have insurance, may not. Not a lawyer.
- Patient advocate: A friend, adult child, or financial counselor helping someone else dispute bills.
- Out-of-state contributor: A developer who wants to add their state's law pack to the kit.
As a patient under bills, I want to load this kit into any major LLM and have it know what to do, so that I don't need to be an LLM expert to get help.
AC:
- Given the contents of
llm/,rules/,references/,schemas/,templates/, andtracker/are uploaded to a fresh LLM session, When the patient types "I want to dispute medical bills", Then the LLM followsllm/workflow.mdand asks for the first bill. - Given the LLM has < 200k token context, When the patient follows the staged-load instructions in
llm/system_prompt.md, Then the LLM can still complete the full workflow by loading rules and templates on demand.
Status: shipped (v0.1.0)
As a patient under bills, I want to upload a photo or PDF of a bill and have the LLM extract the structured fields, so that I don't have to transcribe anything.
AC:
- Given a clear photo of a US medical bill, When uploaded with the kit loaded, Then the LLM produces a row matching
schemas/bill.tomland asks the patient to confirm before saving. - Given an unclear or partial image, When the LLM cannot read a required field, Then it asks the patient for that field specifically rather than guessing.
Status: shipped (v0.1.0)
As a patient under bills, I want the kit to recognize when a newly uploaded statement is just a reminder for a bill I already have, so that my tracker doesn't fill up with duplicates.
AC:
- Given a bill already exists in the tracker with account number X and balance Y, When a new statement is uploaded with the same account number and a balance within $5 of Y, Then the LLM treats it as a follow-up statement and updates the existing row's
last_statement_datefield rather than creating a new row. - Given the deduplication rules in
schemas/deduplication_rules.toml, When two records match on at least two of {account_number, provider_tax_id, date_of_service, patient_account_id} and balances overlap, Then they are treated as the same bill.
Status: shipped (v0.1.0)
As a patient who had one hospital stay but receives bills from the hospital plus the radiologist plus the ER physician group plus the anesthesiologist, I want the kit to group these as the same encounter, so that I can see the total cost of the stay and apply No Surprises Act analysis across all of them.
AC:
- Given multiple bills share a service date and a facility name, When they are extracted, Then they are linked under an
encounter_idin the tracker and the LLM flags the encounter for No Surprises Act review if any of the providers might be out-of-network.
Status: shipped (v0.1.0)
As a patient under bills, I want the LLM to compare the CPT level coded on my bill against the actual visit I had, so that an upcoded ER visit gets challenged.
AC:
- Given an itemized bill containing E/M code 99284 or 99285, When the patient's described visit is short (under 30 minutes) with simple decision-making, Then the LLM flags the line as "possible upcoding" and references
references/cpt_codes_em.mdfor the documentation requirements.
Status: shipped (v0.1.0)
As a patient under bills, I want the LLM to flag when I'm being balance-billed in a scenario where federal law prohibits it, so that I can use the strongest possible challenge first.
AC:
- Given an emergency-services bill from an out-of-network provider, When extracted, Then the LLM cites the No Surprises Act, references
rules/04_no_surprises_act.md, and offerstemplates/letter_no_surprises_violation.md. - Given a non-emergency bill at an in-network facility from an out-of-network ancillary provider (anesthesia, radiology, pathology, lab, assistant surgeon, hospitalist, intensivist, neonatologist), When extracted, Then the same flag and template are offered.
Status: shipped (v0.1.0)
As a patient under bills, I want the LLM to call out line items priced far above fair-market for my area, so that I have a concrete number to argue down to.
AC:
- Given a line item with a CPT code, When extracted, Then the LLM points the patient to the relevant transparency tool (Turquoise Health, Healthcare Bluebook, FAIR Health Consumer, or the hospital's own price file) and explains how to look up a fair price.
Status: shipped (v0.1.0)
As a patient who received only a summary bill, I want the LLM to draft a certified-mail itemization request that cites the right state statute, so that the provider's 30-day clock starts running.
AC:
- Given the patient's state, When the LLM uses
templates/letter_itemization_request.md, Then the rendered letter cites the correct state statute (TN Code § 68-11-220 for Tennessee; for other states, the LLM uses the lookup pattern inreferences/laws_state_template.md).
Status: shipped (v0.1.0)
As a patient with a problematic bill, I want a polite-but-firm dispute letter that names each disputed line item with the legal basis, so that the provider has a clear paper trail of my objection.
AC:
- Given findings from Epic 3, When the LLM uses
templates/letter_initial_dispute.md, Then the letter lists each disputed line with citation, proposes a corrected total, and requests written response within 15 business days.
Status: shipped (v0.1.0)
As a patient whose initial dispute was ignored, I want to escalate with a formal warning of small claims court action, so that the provider's legal cost to defend exceeds the disputed amount.
AC:
- Given the initial dispute has gone unanswered for 30+ days, When the LLM uses
templates/letter_30day_warning.md, Then the letter includes the disputed amount, the patient's prior good-faith efforts, the cost-to-defend argument, and CC lines to the state insurance department, attorney general, and BBB.
Status: shipped (v0.1.0)
As a patient whose ERISA-governed plan denied a claim, I want an appeal letter that argues from plan terms and federal evidence standards rather than emotion, so that I preserve my right to sue under ERISA § 502(a) if denied again.
AC:
- Given a denial letter from an ERISA-covered plan, When the LLM uses
templates/letter_insurance_appeal_erisa.md, Then the appeal cites the plan's Summary Plan Description, attaches medical-necessity evidence, references ERISA § 502(a), and preserves all rights to civil action.
Status: shipped (v0.1.0)
As a patient ignored by a provider or insurer, I want a ready-to-submit state complaint, so that I trigger a regulatory investigation and increase pressure.
AC:
- Given the patient's state, When the LLM uses
templates/complaint_state_doi.md, Then the complaint includes the right agency name, contact info, and statutory hooks.
Status: shipped (v0.1.0)
As a patient whose bill is correctly coded but unaffordable, I want a negotiation letter that anchors to the Medicare rate and demands consideration under the hospital's Financial Assistance Policy, so that I am not pushed into a payment plan I can't sustain.
AC:
- Given a bill with no dispute findings but a balance the patient cannot afford in full, When the LLM uses
templates/letter_hardship_negotiation.md, Then the letter cites IRS § 501(r) where applicable, names reference points (Medicare rate, hospital cash price, fair-market range) with sources, makes a specific dollar offer, and refuses auto-debit and interest charges.
Status: shipped (v0.2.0)
As a patient receiving first written contact from a third-party debt collector on an alleged medical debt, I want to demand validation under FDCPA § 1692g within the 30-day window, so that collection activity is paused and the collector is forced to produce the underlying paper trail.
AC:
- Given a collector's first written communication received within the last 30 days, When the LLM uses
templates/letter_fdcpa_validation.md, Then the letter demands the original-creditor name and address, the signed contract, an itemized statement, EOB, payments accounting, chain of assignment, state licensure, and date of last activity, and preserves FDCPA and FCRA rights. - Given the bill is from the original creditor (hospital or doctor's office) rather than a third-party collector, When the patient asks for this template, Then the LLM declines and routes to
letter_initial_dispute.mdorletter_hardship_negotiation.mdinstead.
Status: shipped (v0.2.0)
As a patient running a multi-month dispute process, I want to download my updated tracker as a CSV at the end of every session, so that I can re-upload it next time without losing context.
AC:
- Given any session, When the patient says "save my progress" or the LLM detects the conversation is wrapping, Then the LLM outputs a complete CSV matching
schemas/tracker.tomland tells the patient where to save it.
Status: shipped (v0.1.0)
As a returning patient, I want to resume by uploading my tracker and any new statements, so that I don't re-tell my story.
AC:
- Given an uploaded
tracker.csvmatchingschemas/tracker.toml, When the LLM ingests it at session start, Then the LLM summarizes open actions, overdue items, and any deadline within 7 days.
Status: shipped (v0.1.0)
As a patient in (e.g.) Texas, I want the kit to find the right Texas statutes without me knowing them, so that the kit isn't TN-only.
AC:
- Given a patient outside Tennessee, When the LLM hits a state-specific step, Then it follows
references/laws_state_template.mdto find the equivalent statute, agency, and small-claims process, and warns the patient that the citation should be verified before sending mail.
Status: shipped for six states (Tennessee v0.1.0, Georgia v0.2.0, California + Texas + New York + Florida v0.4.0). Long-tail state coverage remains open for contributor PRs.
How to apply: Track contributor PRs that fill in remaining states using references/laws_state_template.md as the checklist.
As a patient receiving a balance bill from an out-of-network ground ambulance provider, I want the kit to recognize that ground ambulance is excluded from the federal No Surprises Act, route my case based on whether my state has its own protection, and draft the correct dispute letter, so that I am not stuck paying a $3,000 surprise bill that the federal Act explicitly leaves unprotected.
AC:
- Given a ground-ambulance bill, When the patient's state is on the list in
rules/10_ground_ambulance.mdand the plan is not ERISA-self-funded, Then the LLM usestemplates/letter_ground_ambulance.mdVariant A citing the specific state statute. - Given a ground-ambulance bill, When the patient's state has no protection or the plan is ERISA-self-funded, Then the LLM uses
templates/letter_ground_ambulance.mdVariant B arguing UCC § 2-305 with the Medicare ambulance fee schedule as the floor anchor. - The LLM asks up-front whether the patient's plan is self-funded ERISA before choosing between variants.
Status: shipped (v0.3.0)
As a patient who was uninsured or self-pay for a scheduled service, received (or should have received) a Good Faith Estimate, and is now staring at a final bill more than $400 above the estimate, I want the kit to walk me through filing federal Patient-Provider Dispute Resolution within the 120-day window, so that I get a binding determination from a neutral arbitrator and the collections-pause / credit-protection benefits that attach during PPDR.
AC:
- Given a self-pay patient with a final bill exceeding the GFE by $400+ within 120 days of receipt, When the LLM walks them through
rules/11_ppdr_walkthrough.md, Then the patient has a complete checklist of evidence to upload to the federal IDR portal and an action logged in their tracker with the appropriate deadline. - Given a patient who was entitled to but never received a GFE, When the LLM identifies this, Then it surfaces a parallel CMS complaint at 1-800-985-3059 and notes the failure-to-provide-GFE is itself an NSA violation independent of PPDR.
Status: shipped (v0.3.0)
As a patient with a bill from a non-profit hospital that I cannot afford in full, I want the kit to draft a Financial Assistance Policy application request that cites the applicable IRS regulations, triggers the hospital's procedural obligations during pendency, and refuses extraordinary collection action while the application is processed, so that I am screened for charity care before any collections clock runs.
AC:
- Given a non-profit hospital bill, When the patient uses
templates/letter_financial_assistance_application.md, Then the letter requests the FAP, Plain Language Summary, application form, Billing & Collections Policy, and AGB calculation; states the patient's eligibility factors; and demands suspension of extraordinary collection action under 26 CFR § 1.501(r)-6. - Given a non-responsive hospital after 30 days, When the LLM logs the timeout, Then it surfaces the escalation path (IRS Form 13909 plus state AG complaint).
Status: shipped (v0.3.0)
As a patient whose hospital has not published a compliant machine-readable file of standard charges, I want a CMS complaint that produces regulatory pressure on the hospital, so that I gain access to the negotiated rates and cash prices the federal rule entitles me to see and which would anchor my underlying billing dispute.
AC:
- Given a hospital without a compliant MRF on its website, When the patient uses
templates/complaint_cms_hpt.md, Then the complaint cites 45 CFR Part 180, identifies the specific deficiency (no MRF / incomplete MRF / no consumer display / access-barrier), and includes timestamped screenshots as evidence.
Status: shipped (v0.3.0)
As a Medicare beneficiary whose claim was denied by the MAC, by a Medicare Advantage plan, or by a Part D plan, I want to file the appropriate appeal at the correct level with the correct deadlines, so that I exhaust the five-level Medicare appeal process correctly without losing the right to advance to ALJ or federal court.
AC:
- Given a denied Medicare claim, When the LLM walks the patient through
rules/12_medicare_appeals.md, Then it identifies which Medicare part (A/B, C, D) and which level (1-5) applies, calculates the filing deadline from the date of the prior decision, and usestemplates/letter_medicare_appeal.mdto draft the Level 1 or Level 2 request with all required elements per 42 CFR § 405.946 / § 422.566 / § 423.580. - Given an expedited-review-eligible situation, When the LLM detects clinical urgency, Then it renders the expedited-review section and shortens the response deadline accordingly.
Status: shipped (v0.4.0)
As a Medicaid enrollee whose service was denied by my MCO, I want to file the MCO internal appeal within 60 days and, if still denied, the state fair hearing within the state's deadline, so that I exhaust the federal-floor appeal process without losing the right to state-level review.
AC:
- Given a Medicaid MCO denial, When the LLM uses
templates/letter_medicaid_appeal.md, Then it identifies the correct MCO appeal address, cites 42 CFR § 438.402 et seq., includes the Aid Paid Pending option where applicable, and routes to the state fair hearing as Step 2. - Tennessee-specific path: Given a TennCare denial, When the patient asks for state fair hearing, Then the letter is addressed to TennCare Solutions and references Tennessee Justice Center as a free-help option.
Status: shipped (v0.4.0)
As a patient whose dental insurer downcoded a procedure or bundled separately-billable procedures, I want an appeal letter that cites the state's non-covered-services statute and the ADA's CDT code requirements, so that I (and my dentist) recover the correct payment.
AC:
- Given a dental EOB showing downcoding or bundling, When the LLM uses
templates/letter_dental_dispute.md, Then the letter identifies the specific CDT code(s) at issue, cites the state non-covered-services statute (Tennessee § 56-2-305 as the worked example), and demands reprocessing with attached clinical documentation. - Given a state that has not enacted a non-covered-services statute, When the LLM cannot cite a state-specific anti-downcoding law, Then it falls back to the plan terms and the implied covenant of good faith.
Status: shipped (v0.4.0)
As a patient unfamiliar with the alphabet soup of health-care billing, I want to look up any term used by the kit in one place, so that I don't lose context to terminology.
AC:
- Given any acronym used in a rule, template, or reference file, When the patient searches
references/glossary.md, Then they find a plain-English definition.
Status: shipped (v0.4.0)
As a new patient picking up the kit, I want quick answers to recurring questions ("the bill is overdue, what now?", "do I need a lawyer?", "what if I missed a deadline?"), so that I don't have to read every rule file to get unstuck.
AC:
FAQ.mdcovers ≥ 20 common scenarios with answers grounded in specific rules.- Each FAQ answer cross-references the rule or template that handles the case.
Status: shipped (v0.4.0)
As a patient using a small local model or a cloud LLM with limited context, I want a staged-load pattern that doesn't require all kit files in memory simultaneously, so that I can still complete the workflow.
AC:
llm/QUICKSTART_short_context.mddescribes a 7-stage load pattern.- Each stage names the specific files to load and what the LLM should do with them.
Status: shipped (v0.4.0)
As an open-source contributor with knowledge of my state's medical-bill protections, I want clear contribution guidelines, so that my PR meets the kit's quality bar on the first try.
AC:
CONTRIBUTING.mdincludes a checklist for new state packs covering all 12 required sections.- Specifies the citation discipline (URL per claim, verified-on date).
- Lists the cross-references that must update in lockstep (BUILD_PLAN, CHANGELOG, README, QUICKSTART).
Status: shipped (v0.4.0)
As a technical user, I want a script that confirms my tracker conforms to the schema, so that I can catch typos before re-uploading to the LLM.
AC:
scripts/validate_tracker.pyruns on Python 3.11+ standard library, no dependencies.- Validates header order, date format, decimal format, boolean format, and all enum / controlled-vocabulary fields.
- Returns exit code 0 on valid, 1 on invalid with errors to stderr.
Status: shipped (v0.4.0)
As a maintainer, I want unit tests for scripts/validate_tracker.py, so that schema changes are caught before they reach contributors.
AC:
tests/test_validate_tracker.pycovers the happy path, missing-required-column, bad-date, bad-decimal, bad-enum, bad-findings-token, and header-order-mismatch cases.- Tests run with
python -m pytest tests/and pass. - GitHub Actions workflow at
.github/workflows/ci.ymlruns the validator and pytest on every push and PR to main.
Status: shipped (v0.5.0)
As a first-time contributor opening an issue or PR, I want structured templates that prompt me for the right information, so that my contribution doesn't bounce on missing context.
AC:
.github/ISSUE_TEMPLATE/contains bug, state-pack-request, and content-correction templates, each requiring source URLs where applicable..github/PULL_REQUEST_TEMPLATE.mdhas a checklist for state packs, templates, rules, schema changes, factual corrections, and other change types.CODE_OF_CONDUCT.mdadapted from Contributor Covenant 2.1.SECURITY.mddefines scope and vulnerability-reporting channel.
Status: shipped (v0.5.0)
As a new user with a complex multi-bill, multi-month situation, I want to see the kit handle a realistic scenario before I try it on my own bills, so that I can calibrate expectations.
AC:
examples/multi_encounter_walkthrough.mdshows two hospital encounters with 7 bills, three sessions over six weeks, deduplication of follow-up statements, and resolution with quantified savings.examples/insurance_denial_walkthrough.mdshows an ERISA self-funded plan denial, internal appeal, external review by an IRO, and final coverage.
Status: shipped (v0.5.0)
As a patient who was denied emergency screening, stabilization, or appropriate transfer by a Medicare-participating hospital, I want a complaint letter to CMS that fits the agency's investigation process and preserves my civil right of action, so that I both create regulatory pressure and protect my 2-year statute of limitations.
AC:
- Given an emergency-care denial, When the LLM walks the patient through
rules/13_emtala.md, Then it categorizes the violation (failure to screen, failure to stabilize, inappropriate transfer, refusal over prior unpaid bill, active labor) and drafts the right CMS complaint. - Given the complaint is filed, When the LLM logs the action, Then the 2-year SOL under 42 U.S.C. § 1395dd(d)(2)(C) is calendared and the patient is advised to consult plaintiff-side counsel for the civil action.
Status: shipped (v0.6.0)
As a patient whose provider has delayed access, charged excessive fees, refused electronic transmission, or denied records access entirely, I want an OCR complaint that cites the specific 45 CFR § 164.524 provision violated, so that I unblock the records I need to support my underlying billing dispute.
AC:
- Given a records-request situation, When the LLM walks the patient through
rules/14_hipaa_right_of_access.md, Then it diagnoses which subsection of § 164.524 is in play (no response in 30 days, excessive fee, refused format, procedural barriers, partial response, outright denial). - Given OCR complaint readiness, When the LLM uses
templates/complaint_hipaa_access.md, Then the complaint identifies the specific subsection violated, attaches evidence, and is filed within the 180-day window.
Status: shipped (v0.6.0)
As a patient injured in a motor-vehicle accident, I want the kit to identify all the potential payers (med-pay/PIP, UM/UIM, at-fault driver's BI, my health insurance) and force each provider to bill them in the correct order, so that I don't get hit with chargemaster-priced lien recoveries from my eventual settlement.
AC:
- Given an accident-related bill, When the LLM walks the patient through
rules/15_auto_med_pay.md, Then it routes the case based on whether the state is no-fault or tort, identifies the relevant policy coverages, and (for non-trivial cases) recommends retaining a personal-injury attorney. - Given a hospital is preserving the bill for a settlement lien, When the LLM uses
templates/letter_auto_med_pay.mdVariant B, Then the letter demands the provider bill health insurance under any state-specific insurance-first rule (e.g., O.C.G.A. § 44-14-471(c)). - Given a hospital has perfected a lien, When the LLM uses Variant C, Then the patient receives a structured challenge citing perfection defects, the made-whole doctrine where applicable, and chargemaster-unconscionability arguments.
Status: shipped (v0.6.0)
As a worker with an accepted workers' compensation claim, I want any medical bill that arrives at my address to be redirected to the workers' comp carrier or flagged as improper balance billing, so that I do not pay something I am statutorily exempt from owing.
AC:
- Given a bill stemming from a work-related injury, When the LLM walks the patient through
rules/16_workers_comp.md, Then it confirms the WC claim status, identifies the correct carrier, and produces a redirect letter or escalation to the state workers' comp board as appropriate. - Given the WC claim is contested or denied, When the LLM advises on parallel tracks, Then it surfaces both the state workers' comp appeal path and the health-insurance-with-subrogation interim option.
Status: shipped (v0.6.0)
As a US patient in one of the twelve largest states by population, I want the kit to ship a dedicated state pack with verified citations for my state, so that I do not need to ask the LLM to look up my state's statutes from a template.
AC:
- Dedicated state packs ship for Tennessee, Georgia, California, Texas, New York, Florida, Pennsylvania, Illinois, Ohio, North Carolina, Michigan, Washington.
- Every pack covers the 12 required sections of
references/laws_state_template.mdplus 1-5 state-specific advantages. - Every pack is dated and verified against public sources.
Status: shipped (v0.6.0; long-tail 38 states remain open for community PRs)
As a patient whose medical debt exceeds any realistic repayment plan, I want the kit to identify when bankruptcy makes sense, when other tools should be tried first, and what to bring to a consultation, so that I do not file unnecessarily or fail to file when I should.
AC:
- Given a patient with significant medical debt, When the LLM walks them through
rules/17_bankruptcy_and_medical_debt.md, Then it identifies (a) whether the bill is dispute-eligible (if so, dispute first), (b) whether the patient qualifies for charity care (if so, apply first), (c) the means-test eligibility for Chapter 7, (d) the credit-report impact, (e) the right next step (free legal aid, Upsolve for simple Chapter 7s, a bankruptcy attorney).
Status: shipped (v0.7.0)
As a patient running a months-long dispute process, I want to check my tracker for overdue or upcoming deadlines without re-opening the LLM, so that I don't lose a 30-day response window because I forgot to check in.
AC:
scripts/deadline_watch.pyreads a tracker CSV and groups bills into overdue, due-soon (within a configurable window), and upcoming. Returns exit code 1 if any bill is overdue. Skips settled and closed rows.
Status: shipped (v0.7.0)
As a patient whose dispute has gone unanswered through the kit's escalation ladder, I want to see what filing in small claims actually looks like before I do it, so that I know whether to proceed and how to prepare.
AC:
examples/small_claims_walkthrough.mdcovers the full small-claims filing process for a Tennessee General Sessions case: filing decision, statement of claim drafting, exhibits checklist, hearing preparation script, common defendant arguments and rebuttals, post-judgment collection.
Status: shipped (v0.7.0)
As a new user landing on the repo, I want copy-paste opening prompts for common scenarios, so that I can start disputing tonight without reading every rule file.
AC:
docs/START_HERE.mdprovides a three-minute setup guide, an opening prompt template, and copy-paste prompts for seven common patient scenarios (stack of bills, overpriced bill, denied claim, debt collector calling, hospital charity care, old overdue bill, financial hardship).
Status: shipped (v0.7.0)
As a TRICARE beneficiary receiving a balance bill or claim denial, I want the kit to recognize TRICARE's federal protections (15% balance-billing cap, active-duty zero-cost-share, regional contractor and BCAC referral) and route accordingly, so that I don't apply commercial-plan tactics to a federal program with different rules.
AC:
- Given a TRICARE bill or denial, When the LLM walks the patient through
rules/18_tricare.md, Then it confirms the patient's eligibility status (active duty / retiree / dependent), regional contractor (East: Humana Military; West: TriWest), and identifies whether the bill violates the 15% cap under 10 U.S.C. § 1079(h). Active-duty members are routed to immediate contractor intervention.
Status: shipped (v0.8.0)
As a veteran receiving care from a non-VA provider under the MISSION Act, I want the kit to recognize when the provider is improperly billing me directly instead of the VA TPA, so that I forward the bill to the right place and do not pay something that VA owes.
AC:
- Given a Community Care bill, When the LLM walks the patient through
rules/19_va_community_care.md, Then it confirms the authorization is in place, identifies the right TPA (Optum or TriWest), and routes the bill to the TPA rather than treating it as the veteran's responsibility. - Given a service-connected condition, When billed any amount, Then the LLM flags as likely error and routes to VA Patient Advocate or VSO.
Status: shipped (v0.8.0)
As a patient billed for a telehealth visit, I want the kit to check that the place-of-service code matches the actual modality (home vs office), that modifier 95 or 93 is applied appropriately, that an in-person facility fee was not improperly attached, and that state telehealth-parity rules are followed, so that I do not pay for coding errors.
AC:
- Given a telehealth bill, When the LLM walks the patient through
rules/20_telehealth.md, Then it verifies POS code (02 or 10 vs 11/22), modifier coding (95/93), facility-fee appropriateness, audio-only vs video coding (99441-99443 vs 99213/14 + modifier), and state telehealth-parity applicability.
Status: shipped (v0.8.0)
As a patient with a specific bill in hand, I want a single-page decision tree that points me directly at the right template, so that I do not have to read every rule file to figure out where to start.
AC:
docs/DECISION_TREE.mdcovers the 14+ most common patient scenarios with explicit template recommendations and cross-references to the relevant rules.
Status: shipped (v0.8.0)
As a patient who experienced inadequate language access, disability accommodation, or other discrimination-tinged conduct that affected billing, I want the kit to surface ACA Section 1557 protections and route to HHS OCR, so that I have a federal civil-rights lever in addition to ordinary billing disputes.
AC:
- Given a patient describing an access failure (LEP, disability, etc.), When the LLM uses
rules/21_section_1557.md, Then it categorizes the violation, drafts a parallel Section 1557 dispute, and routes to OCR within the 180-day complaint window.
Status: shipped (v0.9.0)
As a patient billed for an air-ambulance transport, I want the kit to apply federal NSA protections (which cover air ambulance, unlike ground ambulance) and address the practical pricing issues, so that I do not pay illegal balance bills and can negotiate the legal in-network cost-share down where applicable.
AC:
- Given an air-ambulance bill, When the LLM walks the patient through
rules/22_air_ambulance.md, Then it confirms NSA applicability, identifies balance-billing violations, flags ADA preemption of state remedies, and routes to NSA reprocessing or hardship negotiation depending on whether the disputed amount is balance-billed or in-network cost-share.
Status: shipped (v0.9.0)
As a patient deciding whether to pursue a dispute, I want rough patterns of typical settlement amounts, time-to-resolution, and success rates by track, so that I can decide whether a fight is worth picking.
AC:
docs/COMMON_OUTCOMES.mdprovides public-source patterns for each major dispute track (itemization, initial dispute, NSA, insurance appeal, § 501(r), FDCPA, small claims, hardship, bankruptcy).- Time-to-resolution figures are provided for the most common patient questions.
Status: shipped (v0.9.0)
As a patient starting a dispute, I want to read once about the most common patient-side mistakes, so that I do not undermine my own case before I begin.
AC:
docs/ANTI_PATTERNS.mdcovers 20+ common patient-side mistakes (paying the first bill, auto-debit on file, vague disputes, threatening too much/too little, confusing EOB with bill, etc.) with the right move for each.
Status: shipped (v0.9.0)
As a patient on an ACA marketplace plan whose claim was denied, I want the kit to recognize that the appeals framework differs from ERISA and Medicare and route to the right combination of internal appeal, external review by IRO, and state insurance department complaint, so that I do not miss the binding-IRO-decision lever unique to ACA-compliant plans.
AC:
- Given a denial from a marketplace plan, When the LLM walks the patient through
rules/23_aca_marketplace.md, Then it routes to internal appeal under 45 CFR § 147.136, followed by IRO external review with binding decision, plus parallel state DOI complaint.
Status: shipped (v0.10.0)
As a Medicare beneficiary surprised by observation-status billing (Part B cost-sharing instead of Part A, or denied SNF coverage because no qualifying three-day inpatient stay), I want the kit to surface reclassification and appeal paths, so that I get the correct financial treatment for a hospitalization that clinically looked like an inpatient stay.
AC:
- Given a Medicare patient with observation-status billing concerns, When the LLM walks them through
rules/24_observation_status.md, Then it covers the two-midnight rule, the MOON notice requirement, Condition Code 44 reclassification process, SNF three-day rule, self-administered-drug refund pathway, and the SHIP / Center for Medicare Advocacy resources.
Status: shipped (v0.10.0)
As a patient running a months-long dispute, I want clear guidance on what paperwork to keep, where, for how long, and how to organize it, so that I don't lose key evidence and don't drown in unnecessary paper.
AC:
docs/RECORDS_RETENTION.mdcovers what to keep (provider, insurer, regulator, contemporaneous notes, pricing evidence), what to throw away, retention periods by statute-of-limitations type, naming conventions for digital storage, and special cases (bankruptcy, settlement confirmation, deceased patients).
Status: shipped (v0.10.0)
As a patient reading an itemized bill, I want a quick reference for the most common procedure codes that appear on medical bills, so that I can orient myself without needing a paid AMA subscription.
AC:
references/cpt_quick_reference.mdcovers the highest-frequency CPT and HCPCS codes for imaging, lab, common procedures, surgical, ambulance, DME, and J-codes. Includes the common modifiers and place-of-service codes that affect billing. Honors AMA copyright by paraphrasing rather than redistributing full descriptors.
Status: shipped (v0.11.0)
As a patient with a hospital bill, I want to find and read the hospital's machine-readable file of standard charges, so that I can argue from the hospital's own published prices rather than third-party estimates.
AC:
references/hpt_mrf_format.mddescribes the CMS template format, the discoverable-URL pattern, what to look for in the file, common compliance failures, and how to cite the MRF in a dispute letter.
Status: shipped (v0.11.0)
As a patient in Utah, Iowa, Nevada, or Arkansas, I want a dedicated state pack rather than the LLM looking up my state's statutes from the template, so that my dispute letters cite the right authorities with confidence.
AC:
- Dedicated state packs ship for UT, IA, NV, AR matching the 12-section format of existing packs. Total: 32 state packs covering ~82% of US population.
Status: shipped (v0.11.0)
As a patient or contributor opening the repo for the first time at 100+ files, I want a single-page cross-reference index that maps every file by scenario, type, federal law, and state, so that I can find what I need without skimming everything.
AC:
docs/INDEX.mdprovides scenario-, type-, law-, and state-based navigation.- Every rule, template, reference, schema, example, and governance file is listed at least once.
Status: shipped (v0.12.0)
As a user with questions about features added across v0.6-v0.11, I want the FAQ to cover them rather than reading every rule file, so that I can answer common scenarios quickly.
AC:
- FAQ.md adds 18+ entries covering EMTALA, HIPAA right of access, auto med-pay, workers' comp, bankruptcy, TRICARE, VA Community Care, telehealth, ground ambulance, air ambulance, observation status, ACA marketplace, Section 1557, plus process-and-tooling questions for the deadline watcher, decision tree, common outcomes, anti-patterns, records retention, START_HERE, CPT quick-reference, and HPT MRF format.
Status: shipped (v0.12.0)
As a patient in Kansas, Mississippi, New Mexico, or Nebraska, I want a dedicated state pack rather than the LLM looking up my state's statutes from the template.
AC:
- Dedicated state packs ship for KS, MS, NM, NE matching the existing 12-section format. Total: 36 state packs covering ~84% of US population.
Status: shipped (v0.12.0)
As a patient with an itemized bill, I want the kit to compare each CPT against the Medicare allowable rate and surface a UCC § 2-305 counter-offer anchor, so that I have concrete evidence the bill is not a good-faith open-price term.
AC:
- Given an itemized bill, When
scripts/fetch_price_benchmarks.pyruns, Then it writesBillers/<slug>/_benchmarks.csvwith one row per CPT showing billed amount, Medicare national rate, ratio, and FAIR Health / Bluebook URLs. - Given
_benchmarks.csvhas at least one row withratio_billed_to_medicare >= 1.50, Whenscripts/check_completeness.pyruns, Then the bill'sbenchmarks_availableflips to Y andnext_actionbecomesnegotiate_counter_offer. - Given the counter-offer track is active, When
scripts/draft_letters_by_state.pyruns, Then it draftsLETTER_COUNTER_OFFER.mdfromtemplates/letter_negotiation_counter_offer.mdwith the line-item benchmark table embedded and an auto-computedcounter_offer_amountof 200 % of the sum of Medicare allowables (or 20 % ofcurrent_balanceas fallback).
Status: shipped (v0.13.0)
Story 19.2, Audit each bill for duplicates, unbundling, modifier-25, late fees, and quantity inflation
As a patient under a bill, I want the kit to automatically detect the most common billing errors Marshall Allen documents, so that my dispute letter cites structured findings rather than relying on the LLM to re-discover them every run.
AC:
- Given an itemized bill, When
scripts/audit_billing_errors.pyruns, Then it writesBillers/<slug>/_audit.csvwith rows for each detected: duplicate CPT same DOS, NCCI unbundling (fromreferences/ncci_pairs_common.csv), modifier-25 stacking with an E/M code, late-fee / finance-charge keywords, service-not-received language, and quantity-inflation flags.
Status: shipped (v0.13.0)
As a patient who has mailed a dispute letter, I want the kit to draft the matching state insurance-department or attorney-general consumer-affairs complaint same day, so that parallel pressure reaches the bad actor without my having to research each state portal.
AC:
- Given a dispute or counter-offer letter has been drafted (or its sent-date is populated), When the drafter runs, Then it produces
COMPLAINT_DOI.mdusingtemplates/complaint_state_doi.mdfilled in with the right portal URL and mailing address for the patient's state fromreferences/doi_portals.md.
Status: shipped (v0.13.0)
As a patient whose dispute and 30-day warning have gone unanswered, I want the kit to draft a county-agnostic small-claims / general-sessions civil warrant with five claim theories preserved (UCC § 2-305 declaratory, NSA, HPT non-compliance, state itemization statute, FDCPA), so that I can file with the county clerk by transcribing onto their standard form.
AC:
- Given
thirty_day_warning_sent_dateis populated and nosmall_claims_filed_dateis set, When the drafter runs, Then it producesSMALL_CLAIMS_CIVIL_WARRANT.mdfromtemplates/small_claims_civil_warrant.md.
Status: shipped (v0.13.0)
As a patient whose dispute letter received a non-substantive reply, I want the kit to draft a tighter second written dispute that identifies what was unaddressed and gives a 15-business-day final window, so that I have a clean record before filing the DOI complaint or small claims.
AC:
- Given
dispute_letter_sent_dateis populated and the user has recorded a non-substantive response (via the notes column or viascripts/log_interaction.py --action response_received), When the drafter is run with the dispute_reply template override, Then it producesLETTER_DISPUTE_REPLY.mdfromtemplates/letter_dispute_reply.mdselecting from blocks A-E based on what the user characterized in the reply.
Status: shipped (v0.13.0)
As a patient with old medical debts, I want the kit to flag accounts whose state-law SOL has expired or expires soon, so that I can preserve the SOL defense without accidentally re-aging the debt.
AC:
- Given a tracker CSV, When
scripts/deadline_watch.py --sol --state <CODE>runs, Then accounts past the state's written-contract SOL appear in an "SOL expired" group and accounts within--sol-warndays appear in an "SOL approaching" group, withreferences/sol_by_state.mddocumenting the state-by-state table. - The output includes a reminder not to confirm the debt or make a partial payment on a SOL-expired account without first researching the state's re-aging rule.
Status: shipped (v0.13.0)
As a plan participant whose written § 1024(b)(4) document request was ignored, I want the kit to draft the § 502(c)(1) statutory-penalty demand at $110/day so I can recover the penalty (payable to me) or motivate the administrator to cure, so that the document delay carries actual cost.
AC:
- Given an SPD or plan-document request was sent and at least 45 calendar days have elapsed without cure, When the drafter is run with the erisa_502c_penalty template override, Then it produces a demand letter computing the accrued penalty days × $110 with a 15-day cure window before federal-court filing.
Status: shipped (v0.13.0)
As a patient suspicious that a line item was billed but not rendered, I want the kit to draft a HIPAA § 164.524 records request that invokes the 30-day statutory clock and the state's per-page fee cap, so that I can compare the medical record to the bill before deciding what to dispute.
AC:
- Given the audit detector has surfaced a
service_not_received_suspectedfinding (or the user explicitly requests records), When the drafter is run with the records_request_hipaa template override, Then it producesLETTER_RECORDS_REQUEST_HIPAA.mdfromtemplates/letter_records_request_hipaa.mdinvoking § 164.524 and the applicable state fee cap.
Status: shipped (v0.13.0)
As an uninsured or self-pay patient, I want the kit to draft a Good Faith Estimate demand and, when the final bill exceeds the GFE by $400+, a Patient-Provider Dispute Resolution submission for the federal portal, so that I have access to the federal NSA framework that applies to me.
AC:
- Given a self-pay patient and a scheduled or recently-billed service, When the drafter is run with the good_faith_estimate_request override, Then it produces
LETTER_GFE_REQUEST.mdfromtemplates/letter_good_faith_estimate_request.md. - Given a final bill that exceeds a previously-issued GFE by $400+, When the drafter is run with the ppdr_initiate override, Then it produces a PPDR submission from
templates/letter_ppdr_initiate.mdwith the line-item comparison table.
Status: shipped (v0.13.0)
As an accident-injured patient whose hospital has filed a statutory lien against a tort recovery, I want the kit to draft a six-ground lien challenge (chargemaster vs allowed, bill-insurance-first, NSA preemption, statutory cap, defective notice, made-whole), so that the lien is withdrawn or reduced to the contracted rate before settlement.
AC:
- Given the user flags
findings = "hospital_lien_threatened"on a tracker row, When the drafter is run with the challenge_hospital_lien override, Then it producesLETTER_CHALLENGE_HOSPITAL_LIEN.mdfromtemplates/letter_challenge_hospital_lien.md.
Status: shipped (v0.13.0)
As a plan participant facing an insurer subrogation claim against my tort recovery, I want the kit to demand plan documents and preserve the made-whole, common-fund, allocation, and NSA-carve-out defenses, so that the plan's reimbursement is reduced or eliminated.
AC:
- Given the user has received a subrogation questionnaire or letter of representation, When the drafter is run with the subrogation_response override, Then it produces
LETTER_SUBROGATION_RESPONSE.mdfromtemplates/letter_subrogation_response.mddemanding the SPD and asserting the four defenses.
Status: shipped (v0.13.0)
As a patient whose disputed medical bill has been reported to a consumer credit bureau, I want the kit to draft an FCRA dispute letter invoking the bureau policies, the federal CFPB rule, the state-law ban (where applicable), and the active-dispute and identity-theft defenses, so that the tradeline is removed or marked in dispute.
AC:
- Given the user records the tradeline on a credit report, When the drafter is run with the credit_report_dispute_fcra override, Then it produces
LETTER_CREDIT_REPORT_DISPUTE_FCRA.mdfromtemplates/letter_credit_report_dispute_fcra.mdselecting the applicable grounds from A-H based on the bill's history.
Status: shipped (v0.13.0)
As a plan participant being balance-billed for an NSA-protected service, I want the kit to demand the plan initiate federal Independent Dispute Resolution against the provider and confirm in writing that my cost-sharing is fixed at the in-network amount, so that the plan-vs-provider fight stays between them.
AC:
- Given an NSA-protected service is being balance-billed, When the drafter is run with the request_insurer_initiate_idr override, Then it produces
LETTER_REQUEST_INSURER_INITIATE_IDR.mdfromtemplates/letter_request_insurer_initiate_idr.md.
Status: shipped (v0.13.0)
As a patient whose injury was work-related or vehicle-accident-related, I want the kit to detect the injury context from the bill and draft a payer-redirect letter to the workers'-compensation carrier or auto med-pay carrier, so that the provider bills the right payer instead of me.
AC:
- Given the canonical bill's sidecar text contains work-related-injury keywords, When the drafter runs, Then it produces
LETTER_WC_CARRIER_REDIRECT.mdfromtemplates/letter_wc_carrier_redirect.mdin parallel with the regular dispute flow. - Given motor-vehicle-accident keywords are present instead, When the drafter runs, Then it produces
LETTER_AUTO_MED_PAY.mdfromtemplates/letter_auto_med_pay.mdin parallel with the regular dispute flow.
Status: shipped (v0.13.0)
As a patient with bills from four or more providers for one hospital encounter, I want the kit to recognize the encounter, link the bills, and draft a single combined NSA-ancillary dispute letter addressing every provider, so that the legal argument is made once and the recipients are coordinated.
AC:
- Given multiple bills with date-of-service within ±1 day, When
scripts/check_completeness.pyruns, Then they share anencounter_idof the formE-YYYY-NNN, preserved across runs through user override. - Given an encounter with 4+ distinct billers and at least one bill with an EOB on file, When the drafter runs, Then it produces a single
LETTER_ENCOUNTER_COMBINED.mdfromtemplates/encounter_combined_dispute.mdanchored to the alphabetically-first bill_id in the encounter, with a per-provider table covering every encounter member.
Status: shipped (v0.13.0)
As a patient running a months-long dispute, I want to log every phone call, email, and received response in a structured action log so the dispute drafter can reference the history in subsequent letters, so that the paper trail is intact and citable.
AC:
- Given the user runs
scripts/log_interaction.py --bill-id <id> --action <type> --note <text>, Then a row is appended to<log-dir>/actions.csvwith auto-incrementedA-YYYY-NNNaction_id, validated againstschemas/action.toml, and refused if the bill_id is not intracker.csv(unless--skip-bill-check).
Status: shipped (v0.13.0)
As a patient preparing for a CFO escalation, a DOI complaint, or a court appearance, I want the kit to zip every artifact for one dispute group (bill, EOB, drafted letters, benchmark and audit rows, action log) with a manifest, so that I have a single self-contained record I can hand to a lawyer or judge.
AC:
- Given
tracker.csvhas dispute groups, Whenscripts/bundle_evidence.pyruns, Then<HEALTHBILLS_ROOT>/_bundles/<bill_id>_<YYYYMMDD>.zipis produced per group with aMANIFEST.mdlisting included and missing artifacts. - Given the user has configured rclone, When
scripts/bundle_to_cloud.pyruns withHEALTHBILLS_CLOUD_REMOTEandHEALTHBILLS_CLOUD_PATHset, Then bundles are uploaded with--immutableso existing remote files are not overwritten.
Status: shipped (v0.13.0)
As a kit user who needs to make a phone call to billing, insurance, or a patient advocate, I want scripts and rep-side protocols covering identification, recording-law rules per state, three-step confirmation patterns, and follow-up-letter cadence, so that I do not lose ground on a call.
AC:
references/phone_call_scripts.mdships with six scripts (initial billing call, insurance EOB call, collection-hold call, patient-advocate escalation, CFO escalation, FDCPA validation request) plus universal protocols and a one-party / all-party recording-law state list.
Status: shipped (v0.13.0)
As a patient disputing a non-profit hospital bill, I want a clear walkthrough of which Schedule H fields to extract from the hospital's IRS Form 990 and how to use them in dispute letters, FAP applications, and DOI complaints, so that the hospital's own filings become evidence.
AC:
references/irs_990_review.mddescribes where to find the 990 (ProPublica, GuideStar, IRS), the Schedule H Part I/V/VI fields most useful for disputes, and how to use the data in hardship-negotiation letters, state complaints, IRS Form 13909, and CFO escalation.
Status: shipped (v0.13.0)
As a patient with a hospital bill, I want the kit to fetch the hospital's MRF and extract gross, cash, min/max negotiated, and per-payer rates for the specific CPTs on my bill, so that the dispute letter can argue from the hospital's own published prices in addition to the Medicare benchmark.
AC:
- Given a hospital MRF URL and a CPT list, When
scripts/fetch_mrf.pyruns, Then it content-sniffs the format (CMS template JSON or CSV, Turquoise CSV, TransparentRx JSON, Epic-native CSV) and emits<HEALTHBILLS_ROOT>/_mrf_lookups/mrf_<hospital_slug>_<YYYYMMDD>.csvwith per-code rate bands. references/mrf_vendor_adapters.mddocuments the supported formats and the discoverability patterns.
Status: shipped (v0.13.0)
As a plan participant in an active dispute, I want the kit to read my SPD PDF and emit a structured JSON profile with funding status, cost-sharing, claim and appeal deadlines, subrogation language, and NSA-ancillary implementation, so that ERISA appeals, subrogation responses, and IDR requests cite my actual plan terms.
AC:
- Given an SPD PDF, When
scripts/parse_spd.py --pdf <path> --plan-slug <slug>runs, Then it renders the first 60 pages, sends them to Azure OpenAI, and emits<HEALTHBILLS_ROOT>/_spd_profiles/<plan_slug>.jsonwith the field set documented inreferences/spd_parsing_guide.md. - The profile uses null for fields the SPD does not specify and includes a verbatim quote (capped) of the subrogation and appeal-procedure paragraphs.
Status: shipped (v0.13.0)
As a patient with a bill containing codes from observation, inpatient, mental-health, OB, or immunization categories, I want the bundled medicare_pfs_common.csv to cover them, so that the benchmark CSV is filled out without manual research.
AC:
references/medicare_pfs_common.csvships with ~150 CPT/HCPCS rows at CY2025 national rates, covering ED, observation, inpatient, radiology, lab, cardiology, pulmonology, orthopedic surgery, OB/GYN, mental health, PT, immunizations, common drugs, and supply codes flagged as bundled.
Status: shipped (v0.13.0)
As a patient in a state with strong medical-debt protections (CO, NY, CA, IL, NJ, MN, others), I want the dispute drafter to cite the right state-specific medical-debt-reporting ban, interest cap, charity-care screening mandate, and itemized-bill statute, so that my letters carry the strongest available legal anchors.
AC:
references/medical_debt_protection_by_state.mdships with 15 state entries each covering credit reporting, interest cap, charity-care screening, and itemized-bill on demand. The federal CFPB rule and three-bureau voluntary policies appear at the bottom.
Status: shipped (v0.13.0)
- Roadmap: see
roadmap.jsonfor the structured feature list with release versions. - Changelog: see
CHANGELOG.mdand the git history. - Engineering plan: each rule/template/script is referenced from its story above by relative path.