Tax Filing

Create these folders at the start. Keep the working directory clean — no loose files.

Context Budget Rules

These rules prevent context blowouts that cause compaction:

1. NEVER read PDFs with the Read tool. Each page becomes ~250KB of base64 images (a 9-page return = 1.8 MB). Extract text instead:

   python3 -c "
   import pdfplumber
   with pdfplumber.open('source/document.pdf') as pdf:
       for p in pdf.pages: print(p.extract_text())
   "
   

2. NEVER read the same document twice. Save extracted figures to work/tax_data.txt on first read.
3. Run field discovery ONCE per form as a bulk JSON dump to work/. Do NOT use --search repeatedly.
4. Save all computed values to work/computations.txt so they survive compaction.

Workflow

Step 1: Gather Source Documents

Ask the user what documents they have. Read files from source/ (move them there if needed). Use pdfplumber for PDFs, Read tool for CSVs.

Save all extracted figures to work/tax_data.txt immediately — one section per document with every relevant number.

Step 2: Confirm Filing Details — MANDATORY

You MUST ask the user every one of these questions and WAIT for answers before proceeding. Do NOT skip this step even if you think you know the answers from memory or source documents. Tax returns are legal documents.

• Filing status (Single, MFJ, MFS, HOH, QSS)
• Dependents (number, names)
• State of residence
• Standard vs. itemized deduction preference
• Digital asset / cryptocurrency transactions (Yes/No) — stock trades are NOT digital assets
• Health coverage status (for CA)
• Any estimated tax payments made
• Any other credits or adjustments

Do NOT proceed to Step 3 until the user has answered. "Same as last year" counts as confirmation.

Step 3: Look Up Year-Specific Values

Research from IRS.gov and FTB.ca.gov:

• Federal tax brackets, standard deduction, QDCG 0%/15%/20% thresholds
• State tax brackets, standard deduction, personal exemption credit

Save to work/computations.txt.

Step 4: Compute Federal Return

1. Gross Income: W-2 wages (1a) + interest (2b) + dividends (3b) + capital gain/loss (7)
2. Adjustments → AGI (Line 11)
3. Deductions → Taxable Income (Line 15)
4. Tax: use QDCG worksheet if qualified dividends/capital gains exist
5. Credits, other taxes → Total Tax (Line 24)
6. Payments (withholding, estimated) → Refund/Owed
7. If refund: collect direct deposit info (routing, account, type)

Save all line values to work/computations.txt.

Step 5: Compute Capital Gains (if applicable)

1. Form 8949: individual transactions (Part I short-term, Part II long-term)
2. Schedule D: totals, $3,000 loss limitation, carryover calculation
3. Net gain/loss → 1040 Line 7

Rounding rule: Form 8949 and Schedule D must use exact cents matching the 1099-B / 1099-DA source documents. Only Form 1040 rounds to the nearest whole dollar (Line 7 = round of Schedule D Line 16). Do NOT round amounts on 8949 or Schedule D.

Step 6: Compute State Return (CA Form 540)

1. Federal AGI → CA adjustments → CA taxable income
2. Tax from brackets − exemption credits → total tax
3. Withholding → Refund/Owed

Step 7: Download Blank PDF Forms

Save to forms/ directory.

IRS: Use /irs-prior/ for prior-year forms (/irs-pdf/ is always current year):