# Usage: curl -sSL https://seed.show/healthcare.billing.us | bash -s <install-path>
# <install-path> is the directory where the file should land.

set -euo pipefail
[ -z "${1:-}" ] && {
  echo "install requires a path: curl -sSL https://seed.show/healthcare.billing.us | bash -s <install-path>" >&2
  exit 1
}
TARGET="$1"
mkdir -p "$TARGET"
DEST="$TARGET/seed-fold.9pG8ck.folded.md"

cat > "$DEST" <<'PORTDOWN_C8D9A5DF'
<!--
This is a `.folded.md` archive — a directory packed into one markdown
file. The markers below are load-bearing; don't edit them directly.

To unpack (requires bash — if you have no shell, tell the user):
  1. curl -sSLf https://fold.dom.vin/skill | bash -s <INSTALL_DIR>
  2. <INSTALL_DIR>/fold/scripts/unfold <this-file>
     (or: unfold <this-file>  if fold/scripts is on your PATH)
-->

---
fold: true
marker: cae086
at: 2026-05-07T16:16:07Z
root: seed-pack.bGPI7v
---

<!--fold:cae086@file path="README.md" mode="644"-->
# healthcare.billing.us

US healthcare billing context for agents — structural billing logic, not a rate card.

## What level to work at

**Do not hallucinate:** specific reimbursement rates, code-specific RVU values, MAC-specific coverage policies, or payer-specific contract terms. These change annually (rates), quarterly (policies), or per contract negotiation (terms). Fetch the current values from the sources in `sources.md` before touching any encounter.

**What this bundle gives you:** the mental model of how a claim moves, the failure modes agents consistently trigger, and the structural rules that don't change when CMS updates a fee schedule.

---

## Mental model: a claim is a contract offer

A claim is a written assertion by the provider that a specific service was rendered to a specific patient, was medically necessary, and meets the payer's coverage criteria. The payer's adjudication is its acceptance or rejection of that offer. Every denial is the payer saying the offer didn't meet the terms.

This reframes what an agent is doing. The question is never "what code fits this service?" — it's "will this coded claim satisfy the payer's evidence standard?" Code selection, modifier application, and documentation requirements are all arguments in that contract, not clerical entries.

---

## The claim lifecycle

Every professional and institutional claim follows this arc. Each handoff is a failure point.

**Encounter** — patient presents; the visit happens. The timely filing clock starts here.

**Documentation** — the provider records: chief complaint, history, exam, medical decision-making or time. Documentation is legal evidence the payer will use to justify or deny payment. Narrative quality does not equal billing validity.

**Coding** — documentation translates into:
- ICD-10-CM diagnosis codes (why the service was performed)
- CPT or HCPCS procedure codes (what was performed)
- Modifiers (circumstances that change how a code is priced or bundled)

**Claim assembly** — the coded encounter goes onto a claim form: CMS-1500 (professional) or UB-04 (institutional). Transmitted electronically as ANSI X12 837P/837I or on paper.

**Adjudication** — automated payer edits run in sequence: eligibility, benefits, medical necessity, coverage policy, duplicate detection, CCI edits, fee schedule. Most denials happen here before a human sees the claim.

**Remittance** — the payer issues an ERA (835 transaction) or paper EOB. Each line gets a CARC/RARC pair explaining the payment or denial. Reading remittance codes is prerequisite to appealing or writing off correctly.

**Appeals** — timelines are strict and absolute. Medicare redetermination: 120 days from denial. Most commercial payers: 30-60 days. Appeal rights expire; money is gone.

---

## What agents get wrong

**ICD-10 specificity.** Trunk codes (3-4 character) are statistical; billable codes go to full specificity (up to 7 characters). Payers — especially Medicare Advantage — deny or downcode claims coded at lower specificity when documentation supports a more specific code. The code set updates every October 1. Verify against the current fiscal year's tabular before finalizing any code.

**CPT modifier misuse.** Three modifiers are chronically misapplied:
- **Modifier 25** (significant, separately identifiable E&M same day as procedure): requires documentation that a distinct, separately identifiable service was performed for a different reason than the procedure. Applying 25 to every same-day E&M is the most-audited pattern in professional billing.
- **Modifier 59** (distinct procedural service): used to break CCI edits when a procedure is genuinely distinct — different session, site, or injury. Over-use to bypass bundling edits is a compliance violation, not a billing optimization.
- **Modifier 51** (multiple procedures): appended to secondary and subsequent procedures in the same session. The highest-value procedure gets no modifier; each additional gets 51. Applying 51 to the primary, or omitting it from secondaries, triggers claim-level rejections.

**Place of service (POS) codes.** The same CPT code pays at different rates depending on POS: non-facility (POS 11 office) pays the full rate because physician overhead is included; facility (POS 21 inpatient, POS 22 outpatient hospital, POS 24 ASC) pays the lower facility rate because the facility bills overhead separately on UB-04. Wrong POS quietly pays the wrong rate — sometimes overpaying, sometimes underpaying — and attracts post-payment audit.

**Medical necessity documentation.** Payers pay for services that meet their coverage criteria, not services that happened. Local Coverage Determinations (LCDs) for Medicare and medical policies for commercial payers specify which diagnoses and clinical conditions support coverage for each CPT code. A complete, accurate clinical note that doesn't map to those specific documentation requirements still denies for "medical necessity not established."

**Timely filing.** Medicare requires filing within 12 months of date of service. Most commercial payers: 90-180 days from DOS; some managed care contracts as short as 60 days, or 60-90 days from primary adjudication for secondary claims. Timely filing denials cannot be appealed on clinical grounds — there is no override, no reopening. Do not surface a billing workflow without surfacing the applicable filing deadline.

**ABN requirements.** An Advance Beneficiary Notice of Noncoverage is required before providing a Medicare-covered service you expect Medicare to deny. Without a valid ABN, the provider cannot bill the patient for that service if Medicare denies it. ABNs are mandatory for voluntary and elective services Medicare may consider not medically necessary; they are not required for services Medicare never covers (non-covered services) or for emergency situations. Issuing an ABN without understanding which category applies creates compliance risk on both sides.

---

## Stable structural facts

**Claim form types**
- CMS-1500 (02/12 revision): professional claims — physicians, NPPs, outpatient therapy, DME. Maintained by NUCC.
- UB-04 (CMS-1450): institutional claims — hospitals, SNFs, home health, hospice. Maintained by NUBC.

**ANSI X12 transaction sets**
- 837P: professional claim
- 837I: institutional claim
- 835: remittance advice (payment/denial explanation)
- 270/271: eligibility inquiry and response
- 276/277: claim status inquiry and response

**Adjustment reason code prefixes (CARC/RARC)**
- **CO** (Contractual Obligation): per provider-payer contract; provider cannot bill patient.
- **PR** (Patient Responsibility): patient owes (deductible, copay, coinsurance).
- **OA** (Other Adjustment): write-off, COB adjustment, neither payer nor patient.
- **PI** (Payer Initiated): payer-applied adjustment not covered by other categories.

The CARC prefix determines the response: CO → write off; PR → bill patient; OA → write off or coordinate; PI → review and appeal if warranted.

**Revenue cycle stages** (see `workflow.md` for the full decision framework)
1. Charge capture
2. Coding
3. Claim submission
4. Payer adjudication
5. Remittance posting
6. AR follow-up
7. Denial management
8. Appeals

---

## What AI is changing

**Coding automation.** NLP-driven coding assistants extract CPT and ICD-10 suggestions from clinical notes. Accuracy varies significantly by specialty and documentation quality. AI suggestions require human review — coders validate that the code matches the note and that the note supports the code; they don't rubber-stamp output.

**Denial prediction.** ML models trained on claims history can flag likely denials before submission, prioritizing edits and documentation gaps. The value is in changing the pre-submission workflow, not in post-denial retrospection.

**Prior authorization support.** AI tools are beginning to automate PA criteria lookup and pre-fill auth requests. As of 2025, CMS has finalized rules requiring payers to use FHIR-based PA APIs (effective 2026 for most payers) — automation here is nascent but moving fast. Verify current PA requirements at the payer level before relying on automated PA decisions.

**What stays human:**
- Payer contract negotiation (rates, carve-outs, term structure)
- Clinical documentation judgment (determining what happened clinically, not just what was written)
- Audit response and appeal strategy (requires reading the specific denial, the specific policy, and the specific record together)
- Compliance determinations (whether a billing pattern crosses the line from aggressive to fraudulent)

**How to frame billing advice.** When an agent provides coding or billing guidance, the correct posture is: "this code appears to fit based on the documentation provided — verify against the current tabular and the applicable payer policy before submission." Never present a code selection as final. The agent's job is to narrow the decision space and surface the right questions; the coder's job is to make the defensible final call.
<!--fold:cae086@file path="sources.md" mode="644"-->
# sources

Fetch these at task time. Do not use cached values for rates, codes, or coverage policies — these update annually (code sets), quarterly (LCD/NCD policies), and per contract cycle (payer-specific rates). Ordered by importance.

1. **CMS ICD-10-CM code lookup** — current fiscal year tabular and index. Verify code validity and specificity before billing. Codes update every October 1; a code valid in FY2024 may be invalid in FY2025.
   https://www.cms.gov/medicare/coding-billing/icd-10-codes

2. **CMS ICD-10-PCS code lookup** — procedure codes for institutional (inpatient) claims. Not used on CMS-1500; used on UB-04 for hospital inpatient services.
   https://www.cms.gov/medicare/coding-billing/icd-10-codes/2025-icd-10-pcs

3. **CMS Physician Fee Schedule lookup** — RBRVS-based rates by CPT code, place of service, and geographic locality. Shows facility vs. non-facility rates side by side. Do not cite a specific rate without fetching current values here.
   https://www.cms.gov/medicare/payment/fee-schedules/physician

4. **CMS Medicare Claims Processing Manual** — chapter-level rules for submission, modifiers, POS codes, and timely filing. Chapter 12 covers professional services; Chapter 25 covers FQHCs and RHCs. Authoritative for Medicare billing mechanics.
   https://www.cms.gov/regulations-guidance/guidance/manuals/internet-only-manuals-ioms-items/cms018912

5. **CMS Local Coverage Determinations (LCDs)** — payer medical necessity policies for Medicare, maintained by MACs. Search by CPT code or condition for documentation requirements. MAC-specific: a policy from Noridian does not apply to a Palmetto-administered beneficiary.
   https://www.cms.gov/medicare-coverage-database/search.aspx

6. **CMS National Coverage Determinations (NCDs)** — coverage policies that apply uniformly across all MACs, superseding LCDs where they overlap. Check NCDs before LCDs.
   https://www.cms.gov/medicare-coverage-database/search.aspx

7. **NUCC: CMS-1500 claim form instructions** — field-by-field reference for professional claims, including the current POS code list and modifier guidance. POS code list also lives here.
   https://www.nucc.org/index.php/resources/instructions

8. **AMA CPT overview** — public-facing description of the CPT code system, category structure, and modifier definitions. Full codebook is subscription-only via AMA or licensed EHR/billing system.
   https://www.ama-assn.org/practice-management/cpt/cpt-overview-and-code-approval

9. **CARC/RARC code lists** — current claim adjustment reason codes and remittance advice remark codes, maintained by X12. Required for interpreting ERA (835) transactions.
   https://x12.org/codes/claim-adjustment-reason-codes

10. **CMS Prior Authorization policies** — service-specific PA requirements for Medicare Advantage and fee-for-service. For commercial payers, PA requirements vary by plan and must be verified at the payer level at the time of service — do not rely on prior authorization from a previous plan year.
    https://www.cms.gov/medicare/prior-authorization
<!--fold:cae086@file path="workflow.md" mode="644"-->
# workflow

The revenue cycle as a decision framework. Each stage has inputs, outputs, failure modes, and timing. Use this to diagnose where in the cycle a problem originated — most downstream denials have an upstream cause.

---

## 1. Charge capture

**What it is.** The process of identifying and recording every billable service performed. A charge is the raw billing unit before coding or claim assembly.

**Inputs.** Clinical documentation (notes, orders, operative reports), encounter forms or superbills, facility charge description master (CDM) for institutional billing.

**Outputs.** A charge record: provider, date, service, quantity, and the facility or department where it was performed.

**Failure modes.**
- *Missed charges.* Services performed but never entered — lost revenue that cannot be recovered after timely filing expires.
- *Duplicate charges.* Same service entered twice; triggers payer duplicate-detection edits on adjudication.
- *Unbundled charges.* Billing component parts of a service that has a comprehensive code — a common compliance risk for procedures with global periods.

**Timing.** Charges should be captured within 24-48 hours of service. Each day of delay compresses the window between capture and timely filing deadline.

---

## 2. Coding

**What it is.** Translation of documented services into ICD-10-CM diagnosis codes, CPT/HCPCS procedure codes, and modifiers.

**Inputs.** Clinical documentation (encounter note, operative report, discharge summary). For coding to be valid, the documentation must support the codes — coders cannot add clinical information not present in the record.

**Outputs.** A coded encounter: primary and secondary diagnoses, procedures with modifiers, and the principal diagnosis for institutional claims.

**Failure modes.**
- *ICD-10 truncation.* Selecting a trunk code when documentation supports full specificity. See README.md for the denial pattern.
- *Code linkage errors.* Diagnosis codes that don't support the procedure — payers check that the ICD-10 on the claim is a covered indication for the billed CPT. Linking the wrong diagnosis to a procedure is a medical necessity denial waiting to happen.
- *Modifier misapplication.* See README.md for the three chronically misused modifiers (25, 59, 51).
- *CCI bundle violations.* CPT code pairs in the CCI (Correct Coding Initiative) edit table cannot be billed together without a valid modifier. Billing bundled pairs without a modifier triggers an automatic denial; using modifier 59 to break a CCI edit without documentation support is a compliance violation.
- *E&M level miscalculation.* Under the 2021+ MDM- and time-based documentation guidelines, E&M levels 99202-99215 are determined by medical decision-making complexity or total time. Overcoding generates overpayment risk; undercoding leaves revenue on the table. Both patterns are audited.

**Timing.** Coding should be complete within 3-5 business days of the encounter for high-volume practices. Delayed coding is the second most common cause of timely filing denials after charge capture lag.

---

## 3. Claim submission

**What it is.** Assembly of the coded encounter onto a claim form and transmission to the payer.

**Inputs.** Coded encounter, patient demographic and insurance information, provider credentialing data (NPI, taxonomy code, group/individual billing NPI), POS code.

**Outputs.** A submitted claim: 837P (professional) or 837I (institutional) transaction, or CMS-1500/UB-04 on paper. A claim number or clearinghouse tracking number.

**Failure modes.**
- *Eligibility not verified.* If insurance information has changed since the last visit, the claim goes to the wrong payer or to a patient who is no longer covered. Verify eligibility (270/271 transaction) on or before the date of service, not at the time of billing.
- *NPI/taxonomy mismatches.* The billing NPI must match the NPI on file with the payer for the provider's specialty. Taxonomy code mismatches cause credentialing-level rejections.
- *POS errors.* See README.md — wrong POS triggers either a reject or silent rate miscalculation.
- *Clearinghouse rejections.* Claims rejected at the clearinghouse level (before they reach the payer) may not appear in the payer's system, making status tracking unreliable. Treat clearinghouse acceptance as transmission confirmation only, not claim receipt.

**Timing.** Claims should be submitted within 2-3 business days of coding completion. Combined with coding lag, the target is total submission within 5-7 days of the encounter.

---

## 4. Payer adjudication

**What it is.** The payer's automated and (occasionally) manual review of the claim against eligibility, benefits, coverage policies, fee schedule, and CCI edits.

**Inputs.** The submitted claim, the payer's current fee schedule and coverage policies, the beneficiary's active benefits at the date of service.

**Outputs.** A claim decision: paid (at fee schedule or contracted rate), denied, or pended for additional review.

**Failure modes.**
- *Medical necessity denial.* The billed procedure isn't supported by the documented diagnosis under the applicable LCD/NCD or commercial medical policy. The fix is at the documentation level, not the coding level.
- *Authorization denial.* The service required prior authorization that wasn't obtained before the service was rendered. Retro-authorization is payer-specific and often unavailable.
- *Coordination of benefits (COB) errors.* When a patient has multiple payers, claims must be submitted to the primary payer first. The primary's EOB becomes an input to the secondary claim. Sending a secondary claim without the primary's remittance attached is a guarantee of denial.
- *Timely filing denial.* Claim received outside the payer's filing window. Absolute; see README.md.

**Timing.** Medicare processes clean claims within 14 days (electronic) or 29 days (paper). Commercial payers: 30-45 days per most state prompt-payment laws. Claims pended for review (e.g., additional documentation request) pause this clock.

---

## 5. Remittance posting

**What it is.** Recording the payer's payment decision against the original claim in the practice management system.

**Inputs.** 835 ERA (electronic) or paper EOB, original claim record.

**Outputs.** Posted payments, adjustments, patient balances, and denial reasons — each linked to the claim line.

**Failure modes.**
- *Unposted remittance.* Payments received but not posted create AR phantom balances and obscure the true collection rate.
- *Misread CARC codes.* CO vs. PR vs. OA distinctions (see README.md) determine whether to write off, bill the patient, or appeal. Treating a CO (contractual write-off) as PR (bill patient) generates a compliance violation; treating a PR as CO loses patient revenue.
- *Partial payment not flagged.* Payer pays one line but denies another on the same claim. If the partial payment is posted without flagging the unpaid lines for follow-up, the denial evaporates into the AR.

**Timing.** ERA posting should happen within 1-2 business days of receipt. Posting delays cascade: the AR follow-up queue can't work what isn't posted, and unposted denials miss appeal windows.

---

## 6. AR follow-up

**What it is.** Active pursuit of unpaid or underpaid claims. The AR aging bucket (30/60/90/120+ days) is the primary tracking tool.

**Inputs.** Posted claims with open balances, payer response (or lack thereof), claim status responses (277 transactions).

**Outputs.** Claim status updates, corrected claims submitted, payments collected, or claims escalated to denial management.

**Failure modes.**
- *Aging without action.* Claims sitting in 90-120+ day buckets without follow-up are approaching timely filing limits for appeals. Some payers have appeal windows shorter than 90 days.
- *No-response claims.* A claim not appearing in the payer's system at all (clearinghouse rejection, incorrect payer ID) reads as "no response" in the AR, not as a denial. These require a different workflow — resubmission, not appeal.
- *Underpayment not caught.* Payer pays at a rate below the contracted fee schedule. The underpayment posts, the balance goes to zero, and the revenue is gone. Underpayment identification requires contract-level fee schedule comparison at the claim line.

**Timing.** First follow-up: 30 days from submission for commercial, 14 days for Medicare. Second follow-up: 60 days. Claims at 90+ days should be reviewed for escalation or write-off with cause.

---

## 7. Denial management

**What it is.** Systematic categorization and resolution of denied claims. Effective denial management is prospective (using denial patterns to fix upstream processes) and retrospective (resolving current denials).

**Inputs.** Posted denials with CARC/RARC codes, original claim and documentation, payer denial letter if additional documentation was requested.

**Outputs.** Corrected or appealed claims, write-offs with documented cause, upstream process changes.

**Failure modes.**
- *Denial categorization errors.* Treating a coding denial as a medical necessity denial (or vice versa) sends the wrong fix. Read the CARC/RARC pair before routing the work.
- *Appealing unappealable denials.* Timely filing denials, duplicate denials for services that were genuinely duplicated, and non-covered service denials without a valid ABN cannot be recovered through appeal. Knowing what not to appeal saves labor.
- *Pattern blindness.* Individual denials look like one-offs; denial reporting across a 30-day window reveals systematic issues — a payer changing a coverage policy, a coder consistently miscoding a specific service, a front-desk workflow not capturing insurance changes.

**Timing.** Denials should be worked within 5-7 business days of posting. Each day of delay narrows the appeal window.

---

## 8. Appeals

**What it is.** Formal reconsideration request submitted to the payer asserting that the denial was incorrect.

**Inputs.** The denial with reason code, the original claim, clinical documentation supporting medical necessity, applicable LCD/NCD or coverage policy, and the appeal letter.

**Outputs.** Upheld denial, reversed denial (payment), or referral to external review.

**Failure modes.**
- *Missed appeal deadline.* Appeal rights expire absolutely. Medicare redetermination: 120 days from denial notice. Most commercial payers: 30-60 days from denial date. Know the deadline before spending time on the appeal.
- *Wrong appeal level.* Medicare has five appeal levels (redetermination → reconsideration → ALJ hearing → Medicare Appeals Council → Federal District Court). Commercial payers have internal appeal → external appeal. Submitting to the wrong level or skipping a required level voids the appeal.
- *Appealing with the same evidence.* If the original claim was denied for medical necessity and the appeal resubmits the same note without addressing the specific documentation gap the payer cited, the denial will be upheld. The appeal must respond directly to the payer's stated reason.

**Timing.** File within the first third of the appeal window — not the last day. Building a good appeal takes time; a rushed appeal with the wrong evidence wastes the opportunity.
<!--fold:cae086@end-->
PORTDOWN_C8D9A5DF

# ── post ──
MARKER=$(awk '/^---$/ { f++; if (f==2) exit; next } f==1 && /^marker:[[:space:]]/ { sub(/^marker:[[:space:]]+/, ""); print; exit }' "$DEST")
[ -z "$MARKER" ] && { echo "seed: archive has no marker — corrupt" >&2; exit 1; }
awk -v m="$MARKER" -v outdir="$TARGET" '
  BEGIN {
    # Match <!--fold:<m>@file path="X"--> with an optional mode attr after
    # the path (fold emits  mode="644"  on executables).
    file_re = "^<!--fold:" m "@file path=\"([^\"]+)\"( mode=\"[0-9]+\")?-->$"
    end_re  = "^<!--fold:" m "@end-->$"
  }
  $0 ~ end_re { if (current) close(current); exit }
  $0 ~ file_re {
    if (current) close(current)
    line = $0
    sub(/^<!--fold:[^@]+@file path="/, "", line); sub(/".*$/, "", line)
    current = outdir "/" line
    dir = current; sub(/\/[^\/]*$/, "", dir)
    if (dir != current) system("mkdir -p \"" dir "\"")
    printf "" > current
    next
  }
  current { print >> current }
' "$DEST"
SEED_EXTRACTED=$(find "$TARGET" -type f -not -path "$DEST" 2>/dev/null | wc -l)
if [ "$SEED_EXTRACTED" = "0" ]; then
  echo "seed: archive contained no files — refusing to delete the source" >&2
  echo "  archive preserved at: $DEST" >&2
  exit 1
fi
rm -f "$DEST"

echo "" >&2
echo "✓ seed unpacked → $TARGET ($SEED_EXTRACTED files)" >&2
find "$TARGET" -type f | sort | while IFS= read -r _sf; do
  echo "  ${_sf#${TARGET}/}" >&2
done
echo "" >&2
if [ -f "$TARGET/SKILL.md" ]; then
  echo "This seed contains a skill (SKILL.md). Install it in your agent's skills directory." >&2
  echo "" >&2
fi
echo "Install the seed skill if not already installed:" >&2
echo "  https://seed.show/skill" >&2
echo "" >&2
echo "Publisher prompt:" >&2
sed 's/^/  /' >&2 <<'__SEED_PROMPT_END_AC1F2B__'
You have the US healthcare billing context. Read README.md for the mental model — the claim as a contract offer, what agents get wrong (ICD-10 specificity, modifier misuse, POS codes, medical necessity, timely filing, ABN requirements), and what AI is and isn't changing. Read workflow.md for the full revenue cycle decision framework: charge capture through appeals, each stage with failure modes and timing. Fetch sources.md for current codes, fee schedules, and coverage policies before touching any encounter. Never cite specific reimbursement rates or MAC-specific rules from memory — fetch them. Then ask what billing task to work through.
__SEED_PROMPT_END_AC1F2B__
exit 0