An LLM-droppable instruction toolkit for analyzing US medical bills, deduplicating follow-up statements, and running a months-long dispute process with letters, complaints, and a tracking spreadsheet that you carry between sessions.
The ruleset is built primarily from Marshall Allen's Never Pay the First Bill (Portfolio, 2021) and his reporting at ProPublica, plus the federal No Surprises Act, the CMS Hospital Price Transparency Rule, ERISA appeal rights, UCC § 2-305, and state-level consumer protections. See references/ for the full citation list.
A pack of Markdown rules, TOML schemas, and letter templates that you load into any large language model (Claude, GPT, Gemini, a local model) along with one or more medical bills. The model uses the rules to:
- Read your uploaded bills (photos, PDFs, statements, EOBs)
- Deduplicate, because most "new" bills are follow-up statements for the same charge
- Produce an organized tracking spreadsheet you download, edit, and re-upload across the months-long process
- For each bill, recommend the next concrete action: request itemization, check CPT severity coding, dispute the charge, file a state complaint, draft an ERISA appeal, or escalate to small claims
- Draft the letter or complaint for you, citing the actual law that applies to your situation
This repo is the instruction layer. It does not run code. You drop these files into your LLM of choice and let the model do the work.
- Clone or download this repo.
- Open your LLM (Claude.ai, ChatGPT, a local model with file upload, etc.) and start a new conversation.
- Upload
llm/system_prompt.md, every file underrules/, every file underreferences/, every file underschemas/, every file undertemplates/, andtracker/tracker_template.csv. For long-context models, all of it fits in one shot. For shorter-context models, follow the prompts in llm/system_prompt.md for a staged load. - Tell the model "I want to dispute medical bills" and upload your first bill image or PDF.
- The model will follow llm/workflow.md: extract the bill into the tracker, deduplicate against prior statements, recommend the next action, and offer to draft the letter.
- Download the updated tracker after each session. Re-upload it next time alongside any new statements you've received.
A worked walkthrough lives at llm/workflow.md.
| Folder | What it holds | Who uses it |
|---|---|---|
llm/ |
Top-level prompt, end-to-end workflow, and output contracts | The LLM you're driving |
rules/ |
The principles and tactics extracted from Allen's work, one rule per file | The LLM, as its operating manual |
references/ |
Federal laws, dedicated state packs (TN, GA, CA, TX, NY, FL), state-law template for new states, CPT codes, glossary, external resources | The LLM, when it needs to cite something |
schemas/ |
TOML schemas describing bill records, tracker rows, dispute actions, and dedup logic | The LLM, when producing structured output |
templates/ |
Letter and complaint templates with placeholders | The LLM, when drafting correspondence |
tracker/ |
Downloadable CSV tracker plus column dictionary | You, between sessions |
examples/ |
Worked-example sessions showing the kit handling real bill patterns | You, before your first session |
scripts/ |
Optional helpers (currently: a Python tracker-CSV validator) | You, optionally, between sessions |
State packs currently shipped (36, covering roughly 84% of the US population): Tennessee, Georgia, California, Texas, New York, Florida, Pennsylvania, Illinois, Ohio, North Carolina, Michigan, Washington, New Jersey, Virginia, Arizona, Massachusetts, Colorado, Maryland, Missouri, Minnesota, Indiana, Wisconsin, South Carolina, Alabama, Kentucky, Oregon, Oklahoma, Connecticut, Utah, Iowa, Nevada, Arkansas, Kansas, Mississippi, New Mexico, Nebraska. For any other state, the LLM uses references/laws_state_template.md to find your state's equivalents (with a warning to verify before mailing). Contributing a state pack is the single most useful PR, see CONTRIBUTING.md and the issue template under .github/ISSUE_TEMPLATE/state_pack_request.yml.
New to the kit? Start at docs/START_HERE.md for a three-minute setup with copy-paste opening prompts. docs/DECISION_TREE.md is the one-page index from "what kind of bill" to "which template applies." docs/INDEX.md is the master cross-reference map. docs/ANTI_PATTERNS.md covers common mistakes; docs/COMMON_OUTCOMES.md calibrates expectations.
Letter templates currently shipped: itemized-bill request, initial dispute, second written dispute (when the first reply did not address the substance), 30-day warning before small claims, No Surprises Act violation, ERISA insurance appeal, ERISA § 502(c)(1) statutory-penalty demand, state insurance department complaint, hardship negotiation, negotiated counter-offer (UCC § 2-305 framing with embedded benchmark table), FDCPA § 1692g validation request, ground-ambulance dispute (two variants by state law), IRS § 501(r) Financial Assistance application, IRS Form 13909 (tax-exempt organization complaint referral), CMS Hospital Price Transparency complaint, Medicare appeal (Levels 1 and 2 for Parts A/B/C/D), Medicaid appeal (MCO internal plus state fair hearing), dental insurance dispute, EMTALA complaint, HIPAA right-of-access OCR complaint plus the HIPAA § 164.524 records request itself, auto-insurance med-pay dispute (three variants), workers' compensation carrier redirect, hospital-lien challenge (six grounds), plan-subrogation response, FCRA credit-report dispute (eight grounds), insurer-IDR initiation demand, NSA Good Faith Estimate request and PPDR submission for self-pay patients, EOB request, small-claims civil-warrant skeleton, encounter-combined dispute (covering every provider in one hospital encounter), and an attorney-intake packet. Process walkthroughs for federal Patient-Provider Dispute Resolution, the five-level Medicare appeals structure, EMTALA, HIPAA right of access, accident-related billing, and workers' compensation live in rules/. The project roadmap is at roadmap.json.
A local-ops pipeline under scripts/ takes scanned mail, OCRs and classifies it, links bills to EOBs, benchmarks every CPT against Medicare and the hospital's own machine-readable price file, audits for the common billing errors Marshall Allen documents (duplicate codes, NCCI unbundling, modifier-25 stacking, late fees, service-not-received, quantity inflation), and runs a state-machine drafter that produces the right letter at every stage from EOB request through small-claims filing. See scripts/README.md for the pipeline.
Supporting documentation: FAQ.md for common patient questions, references/glossary.md for the alphabet soup, llm/compatibility.md for model-specific guidance, and llm/QUICKSTART_short_context.md for LLMs under 32k tokens. Worked examples in examples/ demonstrate a single session (walkthrough.md), multiple sessions across a months-long dispute process with several encounters (multi_encounter_walkthrough.md), and an ERISA insurance-denial appeal with external review (insurance_denial_walkthrough.md).
Project governance: CONTRIBUTING.md for PR guidelines, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), SECURITY.md for security reporting. Continuous integration in .github/workflows/ci.yml runs the tracker validator and pytest suite on every push and PR.
Most US medical bills contain errors. Hospitals and insurers price-discriminate aggressively and rely on patients not contesting the bill. Federal law (No Surprises Act, ERISA appeal rights, the Hospital Price Transparency Rule) and state law (itemized-bill statutes, unfair claims practices acts) give patients real leverage, but only if used in the right order and with the right paper trail. This kit captures that order, request itemization → verify CPT coding → check for No Surprises Act violations → negotiate at fair market rate → escalate through state complaint → small claims, and stocks the templates needed at each step.
Marshall Allen spent fifteen years documenting how the US healthcare system charges people and concluded that the single highest-leverage thing patients can do is stop paying the first bill until they've checked it. He died May 19, 2024; his successor nonprofit, the Marshall Allen Project, continues the work. This repo turns the playbook he left behind into something an LLM can run alongside you.
This is not legal advice. It is a structured way to apply public laws and well-documented consumer-protection patterns to medical billing disputes. The state-law layer ships with Tennessee and Georgia fully worked out; for other states the kit guides the LLM to look up your state's equivalents using the patterns in references/laws_state_template.md. If your dispute involves more than ~$10,000, suspected fraud, or potential malpractice, talk to a lawyer. Free 30-minute consultations are common, and legal-aid organizations exist in every state.
The kit is jurisdictionally US-only.
PRs welcome, particularly:
- State-specific law packs analogous to the Tennessee worked example
- Additional letter templates (collections disputes under the FDCPA, hospital financial-assistance applications under § 501(r), Good Faith Estimate disputes, etc.)
- Schema improvements to the tracker
- Real-world dedup edge cases that the LLM gets wrong
Keep this repo free of personally identifying information. Examples should use synthetic or clearly fictionalized patient data.
MIT. See LICENSE.
- Marshall Allen, Never Pay the First Bill, Portfolio/Penguin Random House, 2021. Allen's published reporting at ProPublica, including the Surgeon Scorecard project, informs much of the ruleset.
- Lori Todd, the "Insurance Warrior," whose appeal-letter format Allen credits and which informs templates/letter_insurance_appeal_erisa.md.
- All The Hacks podcast with Chris Hutchins, episode "Hacking Healthcare" with Marshall Allen, which is the proximate source for the worked examples in this kit.