From thinking-frameworks-skills
Tracks out-of-pocket HSA-qualified medical expenses via receipts, maintains ledger with running unreimbursed total for tax-free withdrawals, validates against IRS categories. Invoke for new receipts, totals, or planning.
npx claudepluginhub lyndonkl/claude --plugin thinking-frameworks-skillsThis skill uses the workspace's default tool permissions.
- [Overview](#overview)
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
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.
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.
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.
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:
If a candidate is ambiguous, mark qualification: unclear with the IRS Pub 502 reference and let the user confirm.
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
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.
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.
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.
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.
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.
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.
qualification: unclear — surface to user.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
}
}
receipt_path faithfully; flag missing receipts; do NOT count them toward the unreimbursed total.correction_of to amend.