lyndonkl/hsa-receipt-vault

HSA Receipt Vault

Table of Contents

• Overview
• Why this matters
• Input contract
• Qualified expense categories
• Workflow
• Output contract
• Guardrails

Overview

The HSA "shoebox" strategy: pay medical bills out of pocket, save the receipts, let the HSA grow tax-free for decades, then reimburse yourself any time later — there is no time limit on HSA reimbursements as long as the expense was incurred after the HSA was opened. This skill maintains the ledger, validates entries, and exposes the running unreimbursed total.

Why this matters

Every dollar in this ledger is a dollar the household can withdraw tax-free from the HSA at any future point — effectively making the HSA function like a Roth IRA for medical-expense-equivalent dollars, with the optionality to reimburse before retirement if cash is needed.

Input contract

Two modes:

A — single receipt to add:

{
  "date": "2026-03-10",
  "amount_cents": 18500,
  "provider": "Dr. Smith DDS",
  "description": "Dental cleaning",
  "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
  "paid_from_account_id": "acc_chk_001",
  "tx_id": "tx_20260310_004"
}

B — bulk reconcile (scan transactions for category: health.*):

{
  "transactions": [...],
  "existing_vault": [...],
  "hsa_open_date": "2018-01-15"
}

In bulk mode, the skill walks category: health.* transactions, proposes vault entries for those not already in the ledger, and asks the user (via output) to confirm each.

Qualified expense categories

IRS Publication 502 governs HSA-qualified expenses. The skill validates against these high-level categories:

| Qualified | Examples | |---|---| | Medical care | Doctor visits, hospital, surgery, ambulance | | Dental | Cleanings, fillings, extractions, orthodontia | | Vision | Eye exams, glasses, contacts, LASIK | | Mental health | Therapy, psychiatry, prescribed inpatient treatment | | Prescription drugs | Rx, insulin (OTC insulin since 2020) | | OTC medicine and menstrual products | Allowed since CARES Act 2020 | | Medical equipment | Crutches, hearing aids, CPAP, blood-pressure monitors | | Long-term care | Premiums (within IRS limits) and qualified care | | Acupuncture, chiropractic | Yes | | Smoking cessation | Yes | | Weight loss for specific diseases | Only if prescribed for diabetes, hypertension, etc. |

Generally not qualified:

• Gym membership (unless prescribed for a specific medical condition with a Letter of Medical Necessity).
• Cosmetic procedures.
• Vitamins and supplements (unless prescribed to treat a specific condition).
• Marriage / family counseling.
• Insurance premiums (with narrow exceptions: COBRA, while receiving unemployment, Medicare for those 65+).

If a candidate is ambiguous, mark qualification: unclear with the IRS Pub 502 reference and let the user confirm.

Workflow

HSA Vault Progress:
- [ ] Step 1: Validate receipt date is after HSA open date
- [ ] Step 2: Map description to a qualified-expense category
- [ ] Step 3: Confirm receipt_path exists or note it's pending
- [ ] Step 4: Confirm amount paid from a non-HSA account (else not a vault entry)
- [ ] Step 5: Generate id and append to ledger
- [ ] Step 6: Update running unreimbursed_total
- [ ] Step 7: Emit warnings for ambiguous qualifications

Step 1 — Date check

Receipts dated before the HSA was opened are NOT eligible for tax-free reimbursement, no matter when the HSA grows. Reject with a clear warning.

Step 2 — Category mapping

Use the description and the merchant category to map to a qualified category. If unmappable, mark qualification: unclear and suggest the user attach a Letter of Medical Necessity if applicable.

Step 3 — Receipt path

The receipt must be retained — the IRS can request substantiation up to the statute of limitations after reimbursement. Acceptable receipt formats: PDF, JPG, PNG. Path stored relative to the household-finance root: receipts/YYYY/YYYY-MM-DD-provider.ext.

If receipt_path is missing, accept the entry but mark receipt_status: pending and emit a warning. Do not allow pending entries to count toward the running unreimbursed_total — they will, once the receipt is attached.

Step 4 — Source account

A receipt only enters the vault if it was paid from a non-HSA account. Anything paid directly from the HSA debit card or HSA bill-pay is already a tax-free distribution; it doesn't go in the shoebox.

Step 5 — Append

Generate id: rcpt_<year>_<seq>, append to hsa.json.receipt_vault[]. Never mutate prior entries; if a correction is needed, append a correction_of: <prior_id> entry.

Step 6 — Running total

unreimbursed_total_cents = Σ amount_cents WHERE receipt_status = "ok" AND reimbursed = false.

This is the headline number — the dollars the household can pull tax-free at any time.

Step 7 — Warnings

• qualification: unclear — surface to user.
• Receipt date > 1 year old when added — informational; some users batch-enter retroactively, which is fine.
• Amount > $1,000 single receipt — informational; ensure receipt covers the full amount.
• Same date + same provider + same amount as an existing entry — possible duplicate; surface for confirmation.

Output contract

For mode A (single add):

{
  "added": {
    "id": "rcpt_2026_0014",
    "date": "2026-03-10",
    "amount_cents": 18500,
    "provider": "Dr. Smith DDS",
    "description": "Dental cleaning",
    "category": "dental",
    "qualification": "ok",
    "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
    "receipt_status": "ok",
    "paid_from_account_id": "acc_chk_001",
    "tx_id": "tx_20260310_004",
    "reimbursed": false,
    "tax_year": 2026
  },
  "running_totals": {
    "unreimbursed_total_cents": 4435500,
    "by_year_cents": {
      "2024": 1820000,
      "2025": 2150000,
      "2026": 465500
    }
  },
  "warnings": []
}

For mode B (bulk reconcile):

{
  "proposed": [
    {
      "tx_id": "tx_20260118_005",
      "amount_cents": 4500,
      "provider": "CVS Pharmacy",
      "description_raw": "CVS/PHARMACY #04123",
      "suggested_category": "prescription_drugs",
      "qualification": "ok",
      "needs_receipt_upload": true
    },
    {
      "tx_id": "tx_20260201_002",
      "amount_cents": 8500,
      "provider": "Equinox",
      "description_raw": "EQUINOX MONTHLY DUES",
      "suggested_category": null,
      "qualification": "not_qualified",
      "rationale": "Gym memberships are not qualified unless prescribed for a specific medical condition with a Letter of Medical Necessity."
    }
  ],
  "running_totals": {
    "unreimbursed_total_cents": 4435500
  }
}

Guardrails

• HSA-open-date check is non-negotiable. Pre-open expenses can never be reimbursed tax-free.
• Source-account check is non-negotiable. Receipts paid directly from the HSA never enter the vault.
• Receipt retention is the user's responsibility. Track receipt_path faithfully; flag missing receipts; do NOT count them toward the unreimbursed total.
• Append-only ledger. Never mutate. Use correction_of to amend.
• The unreimbursed total is potential, not realized. Surface it as "available for tax-free reimbursement at any time." It does not appear on a tax return until reimbursement actually occurs.
• Do NOT propose reimbursement timing. That's a treasury decision (cash needs vs. continued HSA growth) made by the user with the savings-debt and investment-retirement agents.
• OTC and menstrual products are qualified post-2020. Don't reject these by reflex.