tax-analyzer

name: tax-analyzer description: | US federal and state tax document analyzer and return estimator. Reads tax documents (W-2, 1099-INT, 1099-DIV, 1099-B, 1099-MISC, 1099-SA, Form 3922/ESPP, Form 1098, childcare statements, rental property docs), extracts key figures, calculates AGI, estimates federal tax liability, and produces a professional Excel summary. - MANDATORY TRIGGERS: tax, taxes, tax return, W-2, 1099, tax documents, tax filing, tax owed, refund, AGI, capital gains, ESPP, RSU, rental income, Schedule E, Schedule D - Filing status: Married Filing Jointly (MFJ) - Output: Excel spreadsheet and/or chat summary

Tax Document Analyzer

Analyze US tax documents, extract figures, calculate estimated federal/state tax liability, produce a professional Excel summary. Filing status: Married Filing Jointly.

Workflow

1. Discover documents — scan user's folder for tax files
2. Extract data — parse each document (parallel subagents)
3. Reconcile — cross-check, flag missing docs and discrepancies
4. Calculate — compute AGI, taxable income, tax owed
5. Produce output — Excel spreadsheet and/or chat summary
6. Verify — spot-check calculations programmatically

Step 1: Discover Documents

Scan folder recursively. Categorize by keywords:

File types: .pdf, .png, .jpg, .xlsx. Note unrecognizable files.

Step 2: Extract Data

Read references/document-parsing.md for detailed per-document extraction instructions.

Key principles:

• Use parallel subagents (Task tool) to read multiple documents simultaneously
• PDFs: try Read tool first; if corrupt, try pdftotext via Bash; if image-based, user must provide screenshot
• Screenshots/images: read directly with Read tool (multimodal)
• Extract ALL box values, not just seemingly relevant ones

Critical extraction points:

Step 3: Reconcile

1. W-2 Box 14: If ESPPDD or RESTK present, confirm amounts are ALREADY in Box 1. Never add separately.
2. ESPP lots: Match Form 3922 lots to sales (FIFO). Calculate ordinary income + capital gain per lot. Compare total with W-2 Box 14 ESPPDD.
3. Rental expenses: Cross-check itemized list against individual receipts.
4. Interest/dividends: Sum across all brokerages.
5. Missing docs: Flag expected documents not found.

Step 4: Calculate

Read references/tax-rules.md for brackets, rates, and formulas.

AGI:

W-2 Box 1 (all) + Interest + Dividends + Net Capital Gains + Net Rental Income + Other - Above-the-line deductions = AGI

Tax liability:

AGI - Standard Deduction = Taxable Income
Split into: ordinary income vs qualified dividends/LTCG
Apply marginal brackets to ordinary → ordinary tax
Apply preferential rates to qualified div/LTCG → preferential tax
Total tax - Credits - Withholding = Amount owed/(refund)

If tax year ≠ 2025: web search for that year's standard deduction, brackets, and thresholds.

Step 5: Produce Output

Excel (when user wants a file)

Use scripts/generate_tax_summary.py. Construct the data dict per its docstring, then:

import sys; sys.path.insert(0, '<skill-path>/scripts')
from generate_tax_summary import generate_tax_summary
generate_tax_summary(data, output_path, tax_year=YEAR)

Then recalculate formulas using the xlsx skill's scripts/recalc.py.

Chat summary (always)

Total AGI:           $X
Federal Tax:         $X
Credits:            -$X
Withholding:        -$X
────────────────────────
Estimated Owed:      $X

Step 6: Verify

• Recompute key totals in Python independent of spreadsheet
• Check ESPP ordinary income matches W-2 Box 14 ESPPDD
• Confirm no double-counting of W-2 Box 1 embedded income

Disclaimer

Always include: "I am not a tax professional. This is an estimate to help you plan. Please use tax software or consult a CPA for your actual filing."

Flag items NOT automatically calculated: depreciation, SALT deduction, charitable contributions, HSA/401(k) contributions, student loan interest.