family-finance-report

name

family-finance-report

description

Transform a folder of financial documents (bank statements, credit card exports, checking/savings JSON dumps) into a privacy-preserving consolidated CSV plus a beautiful interactive HTML financial report. Handles PDF, XLSX, JSON, and CSV sources. Strips all personally identifiable information except first names. Categorizes every transaction into 3 levels (source → merchant → category), flags tax-relevant items, and surfaces insights about spending patterns, subscriptions, savings optimization, and tax deductibility. Use when a user drops a folder of statements and says "help me understand our finances", "prepare for tax season", "analyze our spending", or "make sense of all these statements".

Family Finance Report Skill

Purpose

Turn a messy folder of financial documents into a clean, analyzable, shareable picture of a household's money — without ever exposing account numbers, addresses, phone numbers, or last names. The workflow is explicitly designed so a user can hand the resulting HTML report to a spouse, accountant, or financial advisor without privacy concerns.

The canonical workflow:

1. User points you at a folder of financial statements
2. You inventory and identify each file type
3. You ask for the first names of household members (and nothing more)
4. You parse every file, strip PII, categorize transactions, build a CSV
5. You analyze the data and generate an HTML report with charts + insights
6. You present the outputs and explain what's in them

---

CRITICAL: Privacy Rules (NEVER violate these)

These rules exist because the user will share the output with family and friends. A single leaked account number could expose them to fraud.

NEVER write any of these to output files (CSV, HTML, memory, or logs):

• Full account numbers (mask to last 4 digits maximum, or drop entirely)
• Routing numbers
• Social Security Numbers / Tax IDs
• Street addresses, city+state+zip combinations (strip from descriptions)
• Phone numbers (strip from merchant descriptions)
• Last names (of anyone — cardholders, merchants' personal names, employers)
• Email addresses
• Credit card CVV or expiration dates (these shouldn't appear, but strip if found)
• Full employer names if they reveal the person's role (keep generic category like "Federal Salary" or "University Payroll" instead of specific agency names when the user asks for extra privacy)

DO write:

• First names only (when identifying card members or family)
• Merchant names (stripped of address fragments)
• Transaction amounts, dates, and categories
• Account type labels with last-4 only ("Checking ••1234", "Credit Card ••5678")
• Aggregated tax-relevant totals

When in doubt, redact. It is always safe to strip more than needed.

---

Supported File Formats

The skill handles these file types. When you encounter an unfamiliar format, read a sample and adapt — the Python script is designed to be extended.

Format	Example sources	Parser
PDF statements	Chase, BofA, Citi, Capital One, Discover credit card statements	pdfplumber → regex extraction of transaction blocks
XLSX transaction exports	AMEX, Fidelity, Schwab activity exports	openpyxl → auto-detect header row
JSON account dumps	Navy Federal, USAA, PNC (many credit unions)	Built-in json
CSV exports	Almost every bank offers this as fallback	Built-in csv
OFX/QFX	Quicken-style downloads	ofxparse (install on demand)

---

Required Setup (do this ONCE before running the workflow)

The skill needs Python 3 with three libraries. Check if they're installed and install them if missing:

python3 -c "import openpyxl, pdfplumber" 2>&1
# If ModuleNotFoundError:
pip install openpyxl pdfplumber

Some users will have Python in a virtual environment. If pip install fails with "externally-managed-environment", guide them to create a venv or use pipx install. Do NOT suggest --break-system-packages.

---

Workflow: Step by Step

Step 1 — Inventory the folder

Ask the user for the folder path, then list its contents. Classify each file by likely source:

Looking at /path/to/folder, I found:
  📄 5 PDF files matching "*statements*" → credit card statements (Chase?)
  📊 3 XLSX files with "AMEX" in the name → AMEX card exports
  📋 2 JSON files with "Checking" in the name → bank account dumps
  ❓ 1 PDF file named "W2_2025.pdf" → probably tax form, skip

If you find files that look like tax forms (W-2, 1099, 1098) or ID documents, do not parse them. They contain SSNs and personal addresses.

Step 2 — Gather minimal context

Ask the user the following, one topic at a time so it doesn't feel like a form. Nothing here is optional for a high-quality report, but all of it is minimal and non-sensitive.

(a) Household members — first names only

"Whose finances are these? Give me first names only — something like 'Alex and Jamie' or just 'Alex' if you're solo."

(b) The year being analyzed

"Which tax year should I focus on? (I'll filter transactions to that calendar year — other years will be ignored.)"

(c) Tax filing structure

"What's your tax filing situation? Pick one:

• Single
• Married Filing Jointly (MFJ)
• Married Filing Separately (MFS)
• Head of Household (HoH)
• Qualifying Widow(er)"

This drives the correct standard deduction baseline, itemization threshold, and SALT cap behavior in the report insights.

(d) Dependents

"Any dependents? For each, give me just:

• First name (or nickname like 'youngest')
• Age or date of birth
• Relationship ('child', 'parent', etc.)
• Any special notes about them for the year (e.g., 'in preschool until August', 'starts college in fall', 'full-time caregiver')"

Ages and relationships are critical for tax credits:

• Child & Dependent Care Credit: kids under 13 only
• Child Tax Credit: under 17
• American Opportunity / Lifetime Learning: post-secondary students
• Qualifying Relative: other dependents supported by the household

(e) Any specific categorization corrections

"Are there any regular payments in your statements that might be categorized wrong by a generic tool? For example, a preschool that shows up as 'University' in the merchant name, or a recurring charge that's actually a business expense?"

Write any corrections into the family config's category_overrides section so they apply every year.

(f) Files to skip

"Any files in the folder I should ignore?"

Do NOT ask for:

• Full names
• Account numbers
• Tax ID / SSN
• Addresses
• Specific income amounts
• Employer details beyond "federal", "state", "university", "private"
• Anything else that could identify the household

Step 3 — Run the processing pipeline

Use the Python script at scripts/build_report.py (in this skill directory). The script takes a folder path and a JSON config file describing the family members and optional custom categorization rules.

python3 ~/.claude/skills/family-finance-report/scripts/build_report.py \
  --input-dir "/path/to/folder" \
  --output-dir "/path/to/folder" \
  --family-config "/path/to/folder/.family_config.json"

The script will:

1. Discover all supported files in the input directory
2. Parse each file with the appropriate parser
3. Strip PII (account numbers, addresses, phone numbers, last names)
4. Apply the categorization engine
5. Write transactions.csv (the analyzable dataset)
6. Write report_data.json (structured data for the HTML template)

Step 4 — Generate the HTML report

After the script produces report_data.json, use the template at templates/report_template.html as the starting point. The template contains placeholders like {{TOTAL_SPENDING}} that you fill in with real values. Save the final report as Finance_Report_{YEAR}.html in the same folder.

Important: The HTML should be a single self-contained file. Load Chart.js from CDN so the report works offline once loaded. Do not embed any external tracking or analytics.

Step 5 — Surface insights

After generating the raw report, read the CSV and look for non-obvious findings to add to the narrative. These are the insights that wow users:

• Savings rate leaks: Low-yield savings accounts (<0.5% APY) losing thousands to inflation. Compute what a HYSA at current rates would earn.
• Subscription creep: Total monthly recurring charges. Duplicates (two music services, two VPNs, etc.).
• Tax opportunities: Mortgage interest exceeding the standard deduction → should itemize. Medical spending above 7.5% of detected income → deductible portion.
• Spending personality: Top merchant by frequency, biggest single purchase, quietest month, busiest month.
• Family division of labor: Who pays for what (groceries, medical, entertainment). Don't moralize — just describe the pattern.
• Seasonal patterns: November/December spikes (holidays), back-to-school surges, tax-time refunds.

Step 6 — Present the outputs

Tell the user what you produced:

I generated three files in /path/to/folder:

1. transactions.csv — 1,851 categorized transactions, 99% coverage
   (open in Excel/Numbers for ad-hoc analysis)

2. Finance_Report_2025.html — interactive dashboard with charts
   (open in a browser; shareable with family)

3. report_data.json — structured data powering the report
   (keep for re-generation or custom analysis)

Here are the 3 most interesting findings:
- [finding 1]
- [finding 2]
- [finding 3]

---

Categorization Engine

The script ships with ~40 default merchant patterns covering common U.S. merchants (groceries, gas, dining, utilities, subscriptions, etc.). Aim for >95% categorization coverage. For the remaining uncategorized transactions:

1. Read them from the CSV
2. Look for systematic patterns (one merchant appearing many times)
3. Add rules to scripts/category_rules.py for the user's specific spending fingerprint
4. Re-run the pipeline

Never add rules to the shared skill — add them to a user-specific override file at <input_dir>/.custom_rules.py that the script loads if present. This keeps the shared skill generic.

---

Handling New File Formats

If a bank's export format isn't recognized:

1. Read a few lines of the file to understand the schema
2. Show the user the schema and ask "is this the right file?"
3. Add a new parser function to scripts/parsers.py
4. The parser must return a list of dicts with keys: date, amount, raw_description, source_label, card_member
5. Test with python3 -c "from parsers import parse_my_format; print(parse_my_format('/path'))"

---

Sharing the Skill with Family and Friends

When the user asks "how do I share this with my friend", tell them:

Option A: Share the whole skill directory

# On your machine:
cd ~/.claude/skills
tar -czf family-finance-report.tar.gz family-finance-report/

# Send family-finance-report.tar.gz to friend

# Friend installs:
mkdir -p ~/.claude/skills
cd ~/.claude/skills
tar -xzf /path/to/family-finance-report.tar.gz

Option B: Git repository

cd ~/.claude/skills/family-finance-report
git init && git add -A && git commit -m "Initial skill"
gh repo create family-finance-report --public --source=. --push

Friends can then git clone the repo into their ~/.claude/skills/ dir.

Option C: One-liner setup For the least technical friend, generate a shell install script that fetches the skill from the git repo and places it correctly.

---

What Makes a Great Report

The report is the main deliverable. It should make the user go "I can't believe you found all that." Signs of quality:

• Numbers all tie out (total = sum of categories, income + savings = outflows)
• No PII visible anywhere, even hovering over chart elements
• Charts are labeled, tooltips show clean formatted currency
• Narrative connects insights to actions ("you should itemize because...")
• Both spouses / household members feel fairly represented
• Works on mobile (responsive CSS)
• Loads cleanly with no JS errors in the console

What Makes a Bad Report

Things to actively avoid:

• Showing account numbers, even partial
• Calling out one spouse as "the big spender" in a judgmental way
• Making assumptions about income when the data doesn't show it
• Recommending specific financial products by name ("you should buy VTSAX")
• Claiming anything is "definitely deductible" — always "maybe" unless 100% sure
• Embedding fonts, trackers, or phoning home to any external service
• Using emoji characters extensively (they're fine sparingly but don't carpet-bomb — this is a financial document, not a birthday card)

---

Reference Files in This Skill

• scripts/build_report.py — main pipeline (discovery → parsing → CSV → report data)
• scripts/parsers.py — per-format parsers (PDF, XLSX, JSON, CSV)
• scripts/category_rules.py — default merchant categorization patterns
• scripts/pii_scrubber.py — PII detection and redaction utilities
• templates/report_template.html — HTML report template with placeholders
• README.md — installation and sharing instructions for end users