tax-filing

Original source / Raw SKILL.md

---
name: tax-filing
description: >
  United States federal income tax filing assistant for US citizens, resident aliens,
  and nonresident aliens. Guides users through the entire IRS filing workflow:
  determining filer type and filing status, identifying which forms and schedules are
  needed, calculating amounts from source documents (W-2, 1099s, etc.), and filling
  IRS PDF forms using pypdf. This skill covers US federal taxes only — not state,
  local, or non-US tax systems. Use this skill whenever the user mentions taxes, tax
  returns, 1040, 1040-NR, filing status, "which forms do I need", "help me file my
  taxes", "tax prep", deductions, NRA tax filing, nonresident alien taxes, treaty-based
  returns, "check my tax forms", "review my 1040-NR", or any request related to
  preparing a US federal tax return — even if they don't specify their filer type.
  This skill handles the routing and covers both citizen/RA (Form 1040) and NRA
  (Form 1040-NR) workflows end to end, including PDF form filling and validation.
version: 0.2.0
---

# Tax Filing

A guided workflow for preparing US federal income tax returns. This skill covers all filer types — US citizens, resident aliens (RA), and nonresident aliens (NRA) — by first determining the correct filer type, then routing to the appropriate forms and procedures. Both citizen/RA and NRA workflows are fully self-contained in this skill, including PDF form field mappings, cross-form validation, and the safe `update_form.py` script.

## Step 1: Gather Source Documents

Before anything else, ask the user what documents they have. Common source docs:

| Document | What it tells you |
|----------|-------------------|
| W-2 | Wages, federal/state tax withheld, employer HSA contributions |
| 1099-NEC | Contractor / self-employment income |
| 1099-INT | Bank interest |
| 1099-DIV | Dividends (qualified and ordinary) |
| 1099-B | Stock/crypto sales (proceeds and cost basis) |
| 1099-MISC | Other income (royalties, rents, etc.) |
| 1099-SA / 5498-SA | HSA distributions and contributions |
| 1098 | Mortgage interest paid |
| 1098-T | Tuition paid (education credits) |
| I-94 | Travel history (needed for NRA determination) |

If the user has an I-94 or mentions a visa type, that's a strong signal they may be NRA — proceed to Step 2 with that in mind.

## Step 2: Determine Filer Type

This is the critical routing decision. Read `references/filing-status.md` for the full decision tree. The short version:

1. **US citizen or green card holder** → Resident. File **Form 1040**. Go to Step 3a.
2. **Visa holder (F-1, J-1, H-1B, OPT, etc.)** → Apply the **Substantial Presence Test (SPT)**:
   - Count days present: current year days + (1/3 × prior year days) + (1/6 × two years ago days)
   - If total ≥ 183 → **Resident alien** (unless an exemption applies). File **Form 1040**. Go to Step 3a.
   - F-1 and J-1 students are **exempt from SPT** for their first 5 calendar years. They remain NRA. File **Form 1040-NR**. Go to Step 3b.
   - If total < 183 → **Nonresident alien**. File **Form 1040-NR**. Go to Step 3b.
3. **Dual-status** (changed status mid-year) → complex case. Note it for the user and suggest professional review for the transition period.

Ask the user directly if unclear. Don't assume.

## Step 3a: Citizen / Resident Alien Workflow (Form 1040)

Read `references/form-routing.md` to determine which schedules and forms are needed based on the user's income types. For field-level details on individual schedule lines and common pitfalls, read `references/common-schedules.md` when filling specific forms.

### Workflow

1. **Determine filing status** — Single, MFJ, MFS, HOH, QSS (see `references/filing-status.md`)
2. **Map income to forms** — Use the routing table in `references/form-routing.md`
3. **Standard vs. itemized deduction** — 2025 standard deduction: $15,000 (Single), $30,000 (MFJ). Itemize only if total Schedule A deductions exceed this.
4. **Calculate key amounts** from source docs:
   - Total wages (sum of all W-2 Box 1)
   - Total interest/dividends (1099-INT/DIV)
   - Net self-employment income (1099-NEC minus expenses → Schedule C → Schedule SE)
   - Capital gains/losses (1099-B → Form 8949 → Schedule D)
   - Above-the-line deductions (HSA, student loan interest, SE tax deduction → Schedule 1)
   - AGI = Total income - Adjustments
   - Taxable income = AGI - Deduction (standard or itemized)
5. **Fill PDF forms** — Use `scripts/update_form.py` (bundled with this skill) or write equivalent code following the three critical rules:
   - Never write to the same path as input
   - Always use `auto_regenerate=False`
   - Iterate all pages
6. **Cross-validate** — Check the validation rules below
7. **Final review** — Re-extract all fields and confirm consistency

### Cross-Form Validation Rules (Form 1040)

1. **W-2 Box 1 (all) → 1040 Line 1a** (total wages)
2. **Schedule 1 Line 11 → 1040 Line 8** (additional income)
3. **Schedule 1 Line 26 → 1040 Line 10** (adjustments)
4. **1040 Line 9 (total income) = Line 1z + Line 8**
5. **1040 Line 11 (AGI) = Line 9 - Line 10**
6. **1040 Line 13 = standard deduction or Schedule A total**
7. **1040 Line 15 (taxable income) = Line 11 - Line 13 - Line 14**
8. **Schedule C Line 31 (net profit) → Schedule SE Line 2**
9. **Schedule SE Line 13 (SE tax) → Schedule 2 Line 4**
10. **Schedule D Line 16 or 21 → 1040 Line 7** (capital gain/loss)
11. **W-2 Box 2 (all) → 1040 Line 25a** (federal tax withheld)
12. **Estimated payments (1040-ES) → 1040 Line 26**

### Common Mistakes (Citizen/RA)

- Forgetting to file **Schedule SE** when you have 1099-NEC income (self-employment tax is separate from income tax)
- Using the wrong **cost basis** from 1099-B (check Box 1e — if blank, you must calculate it yourself via Form 8949)
- Double-counting **employer HSA contributions** (W-2 Box 12 Code W) — these go on Form 8889 Line 9, not Line 2
- Missing the **$3,000 capital loss limit** — net losses over $3,000 carry forward, they don't all deduct in one year
- Filing as **Single** when **Head of Household** applies (HOH has a larger standard deduction and lower tax brackets)

## Step 3b: Nonresident Alien Workflow (Form 1040-NR)

This section covers the complete NRA filing workflow. For NRA-specific field-to-line mappings, see `references/form-field-maps.md`. For PDF recovery procedures, see `references/pypdf-recovery.md`.

### Critical pypdf Rules

These rules prevent data loss. Violating them will corrupt PDF files. The bundled `scripts/update_form.py` enforces all three automatically — use it instead of writing update logic from scratch.

1. **NEVER write output to the same path as input.** PdfReader uses lazy reading — if you write to the same file, you truncate it while the reader still holds references into it. Page annotations (already in memory) may survive, but the AcroForm catalog gets corrupted during the partial read/write overlap. Always write to a temp path first, then copy.

2. **Always use `auto_regenerate=False`** when calling `update_page_form_field_values()`. The default `True` removes `/AP` (appearance stream) entries from each field. Without appearance streams, some PDF viewers render the field as blank even though the `/V` value is correct — the data is there but invisible.

3. **Iterate all pages** when updating fields, even if you think fields are on page 1. Some IRS forms silently split fields across pages — if you only update page 0, fields on page 1 will be silently skipped with no error.

4. **If a PDF gets corrupted** (field tree broken but annotation values survive):
   - Check annotations directly: `page.get("/Annots")` → `annot.get("/V")`
   - Rebuild the AcroForm `/Fields` array from page annotations
   - Read `references/pypdf-recovery.md` when you see this symptom — it has the full step-by-step repair procedure

### Core Update Function

A bundled script at `scripts/update_form.py` encodes all three critical rules above plus post-write verification. Use it for all form updates:

```bash
# CLI usage — fix a field
python scripts/update_form.py Form1040NR.pdf /tmp/Form1040NR_fixed.pdf --set "f1_53=5000"

# Fix multiple fields and clear one
python scripts/update_form.py Form8843.pdf /tmp/Form8843_fixed.pdf \
    --set "f1_14=338" "f1_17=338" --clear "f1_15"
```

```python
# Or import as a library in your own script
from scripts.update_form import update_form
import shutil

update_form("Form.pdf", "/tmp/Form_fixed.pdf", {"f1_53": "5000"}, clear_fields=["f1_65"])
shutil.copy("/tmp/Form_fixed.pdf", "Form.pdf")  # only then overwrite original
```

The script automatically verifies that fields survived the write and warns if the output looks corrupted. Ensure pypdf is available: `pip install pypdf --break-system-packages`.

### Field Discovery Workflow

Before modifying any form, always extract and map fields first.

**Step 1: Extract all field names and values**
```python
reader = PdfReader("Form.pdf")
fields = reader.get_form_text_fields()
for name, value in sorted(fields.items()):
    short = name.split(".")[-1].replace("[0]", "")
    print(f"{short} = {value}")
```

**Step 2: Map fields to line numbers via Y-position**
Before this step, read `references/form-field-maps.md` for the expected field-to-line table — it covers 1040-NR, 8843, Schedule NEC, Schedule OI, Form 8833, Form 8889, and Schedule 1. Use it as a reference while verifying the Y-position analysis below.

IRS PDFs use positional layout. Extract annotation rectangles to determine which line a field corresponds to:
```python
page = reader.pages[0]
annots = page.get("/Annots")
field_positions = []
for annot_ref in annots:
    annot = annot_ref.get_object()
    t = str(annot.get("/T", ""))
    v = annot.get("/V", "")
    rect = annot.get("/Rect", [])
    ft = str(annot.get("/FT", ""))
    if ft == "/Tx":  # text fields only
        y = float(rect[1]) if rect else 0
        x = float(rect[0]) if rect else 0
        field_positions.append((y, x, t, v))
# Sort by Y descending = top of page to bottom (matches line order)
for y, x, t, v in sorted(field_positions, reverse=True):
    short = t.split(".")[-1].replace("[0]", "")
    print(f"Y={y:.0f} X={x:.0f} {short} = {v}")
```

Compare the Y-position ordering against the physical form layout to create a definitive field-to-line map.

**Step 3: Check checkboxes and radio buttons**
```python
all_fields = reader.get_fields()
for name, field in sorted(all_fields.items()):
    v = field.get("/V", "")
    ft = field.get("/FT", "")
    if ft == "/Btn":
        short = name.split(".")[-1].replace("[0]", "")
        print(f"{short} = {v} (button)")
```

### NRA Form Suite Overview

A typical NRA (F-1 OPT) filing includes these forms. See `references/form-field-maps.md` for complete field-to-line mappings.

| Form | Purpose | Key Fields |
|------|---------|------------|
| 1040-NR | Main return | Income lines, AGI, tax, withholding, refund |
| Schedule 1 | Additional income/adjustments | Contractor income (Line 8h), HSA deduction |
| Schedule NEC | Tax on non-effectively-connected income | Dividends, capital gains, NEC tax |
| Schedule OI | Other information | Visa type, country, treaty claims, days present |
| Form 8843 | Statement for exempt individuals | Days of presence, visa status, exclusion days |
| Form 8833 | Treaty-based return position | Treaty article, exemption amount |
| Form 8889 | HSA | Contributions, employer contributions, deduction |

### NRA Workflow Steps

1. **Gather source docs** (W-2, 1099s, 5498-SA, I-94)
2. **Extract all fields** from all filled PDFs
3. **Build field-to-line maps** using Y-position analysis and `references/form-field-maps.md`
4. **Calculate key NRA amounts**:
   - Total wages (W-2 Box 1) → 1040-NR Line 1a
   - Treaty-exempt income → Line 1k (requires Form 8833)
   - Net wages = Line 1a minus Line 1k → Line 1z
   - Contractor income (1099-NEC) → Schedule 1 Line 8h → 1040-NR Line 8
   - HSA deduction → Form 8889 → Schedule 1 → 1040-NR Line 10
   - AGI = Line 9 (total ECI) - Line 10 (adjustments)
   - NRA cannot take standard deduction (must itemize or take $0)
   - Non-effectively connected income (dividends, capital gains) → Schedule NEC at flat rates
5. **Fill PDF forms** using `scripts/update_form.py` (different output path!)
6. **Cross-validate** every number against source docs and between forms (see rules below)
7. **Apply fixes** using the safe update function
8. **Re-extract and verify** all fields after each fix
9. **Final verification**: read every form one more time and confirm consistency

### Cross-Form Validation Rules (NRA / Form 1040-NR)

After filling, validate these consistency checks:

1. **W-2 Box 1 → 1040-NR Line 1a** (wages)
2. **Schedule 1 Line 10 → 1040-NR Line 8** (additional income from Sch 1)
3. **1040-NR Line 1a minus treaty exempt = Line 1z** (if treaty applies)
4. **1040-NR Line 9 (total ECI) = Line 1z + Line 8** (or sum of all income lines)
5. **1040-NR Line 11a (AGI) = Line 9 - Line 10** (adjustments)
6. **Schedule NEC total tax → 1040-NR Line 23a**
7. **Form 8843 Line 4b = Schedule OI current year days** (days to exclude)
8. **Form 8843 Lines 4a days must match Schedule OI** for each year
9. **W-2 Box 2 → 1040-NR Line 25a** (federal tax withheld)
10. **Form 8833 exemption amount → 1040-NR Line 1k** (treaty exempt income)

### Common NRA Mapping Errors

Watch for these — they are the most frequent mistakes when auto-filling:

- **Contractor income on Line 5b** (pensions) instead of **Line 8** (additional income from Schedule 1)
- **Wages duplicated** on both Line 1a and Line 1h (Line 1h is "other earned income", not a repeat)
- **AGI placed on Line 6** (reserved/future use) instead of Line 11a
- **Treaty exempt amount missing** from Line 1k when Form 8833 is filed
- **Line 1z left empty** — should equal total of Lines 1a through 1h minus exempt
- **Days of presence wrong on Form 8843** — must match I-94 travel history exactly, not assume 365

### US-China Tax Treaty Quick Reference

This section covers the US-China treaty as a concrete example. Similar treaties exist for other countries (e.g., India Article 21(2), South Korea Article 21(1)) — verify article numbers and rates against the specific treaty if your country differs.

For Chinese nationals on F-1 visa:

- **Article 20(c)**: $5,000 exemption on wages/scholarship for students — reported on Line 1k of 1040-NR, requires Form 8833
- **Article 9(2)**: 10% rate on dividends (vs 30% default) — reported on Schedule NEC
- **IRC 871(i)(2)(A)**: Bank deposit interest is exempt for NRAs — do NOT report on any form
- **IRC 871(a)(2)**: Capital gains taxed at 30% flat if present 183+ days — reported on Schedule NEC

## Workflow Summary

1. Gather source documents from the user
2. Determine filer type (citizen / RA / NRA) and filing status
3. Route to the correct workflow (3a for 1040, 3b for 1040-NR)
4. Identify required forms and schedules
5. Calculate amounts from source documents
6. Fill PDF forms safely (different output path, `auto_regenerate=False`, iterate all pages)
7. Cross-validate all numbers between forms
8. Final review — re-extract every form and confirm consistency


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/update_form.py

```python
#!/usr/bin/env python3
"""
Safe PDF form field updater for IRS fillable forms.

Encodes the three critical pypdf rules:
  1. Never write output to the same path as input (causes field tree corruption
     because PdfReader uses lazy reading — writing truncates the file while the
     reader still has references into it).
  2. Always use auto_regenerate=False (the default True removes /AP appearance
     streams, making some PDF viewers show blank fields even though /V has a value).
  3. Iterate all pages (some IRS forms silently split fields across pages).

Usage:
    python scripts/update_form.py INPUT_PDF OUTPUT_PDF [--set FIELD=VALUE ...] [--clear FIELD ...]

Examples:
    # Fix a single field
    python scripts/update_form.py Form1040NR.pdf /tmp/Form1040NR_fixed.pdf --set "f1_53=5000"

    # Fix multiple fields and clear one
    python scripts/update_form.py Form8843.pdf /tmp/Form8843_fixed.pdf \
        --set "f1_14=338" "f1_17=338" --clear "f1_15"

    # Can also be imported and used as a library
    from scripts.update_form import update_form
    update_form("in.pdf", "/tmp/out.pdf", {"f1_53": "5000"}, clear_fields=["f1_65"])
"""

import argparse
import sys
from pathlib import Path

try:
    from pypdf import PdfReader, PdfWriter
except ImportError:
    print("ERROR: pypdf is not installed. Run: pip install pypdf --break-system-packages")
    sys.exit(1)


def update_form(input_path: str, output_path: str, field_updates: dict, clear_fields: list = None):
    """
    Update PDF form fields safely.

    Args:
        input_path:     Path to the source PDF (will not be modified).
        output_path:    Path to write the updated PDF. MUST differ from input_path.
        field_updates:  Dict of {field_name: new_value} to set.
        clear_fields:   Optional list of field names to blank out.

    Raises:
        AssertionError: If output_path == input_path.
        FileNotFoundError: If input_path doesn't exist.
    """
    input_path = str(Path(input_path).resolve())
    output_path = str(Path(output_path).resolve())
    assert input_path != output_path, (
        f"output_path must differ from input_path to prevent corruption. "
        f"Got: {input_path}"
    )

    reader = PdfReader(input_path)
    writer = PdfWriter()
    writer.append(reader)

    # Apply updates across all pages (rule #3: fields can span pages silently)
    for page_idx in range(len(writer.pages)):
        writer.update_page_form_field_values(
            writer.pages[page_idx],
            field_updates,
            auto_regenerate=False  # rule #2: preserve appearance streams
        )

    # Clear specified fields
    if clear_fields:
        clear_dict = {f: "" for f in clear_fields}
        for page_idx in range(len(writer.pages)):
            writer.update_page_form_field_values(
                writer.pages[page_idx],
                clear_dict,
                auto_regenerate=False
            )

    with open(output_path, "wb") as f:
        writer.write(f)

    # Verify the output is readable and fields survived
    verify_reader = PdfReader(output_path)
    fields = verify_reader.get_form_text_fields()
    if not fields:
        print("WARNING: Output PDF has no text fields. Possible corruption — check references/pypdf-recovery.md")
    else:
        print(f"OK: {len(fields)} text fields in output.")
        for name, value in field_updates.items():
            # Match by short name (last segment without [0])
            matched = [v for k, v in fields.items() if name in k]
            if matched and str(matched[0]) == str(value):
                print(f"  Verified: {name} = {value}")
            elif matched:
                print(f"  WARNING: {name} expected '{value}' but got '{matched[0]}'")
            else:
                print(f"  WARNING: {name} not found in output fields")


def main():
    parser = argparse.ArgumentParser(description="Safely update IRS PDF form fields")
    parser.add_argument("input_pdf", help="Path to the source PDF")
    parser.add_argument("output_pdf", help="Path to write the updated PDF (must differ from input)")
    parser.add_argument("--set", nargs="+", metavar="FIELD=VALUE",
                        help="Fields to set, as FIELD=VALUE pairs")
    parser.add_argument("--clear", nargs="+", metavar="FIELD",
                        help="Fields to blank out")
    args = parser.parse_args()

    field_updates = {}
    if args.set:
        for pair in args.set:
            if "=" not in pair:
                print(f"ERROR: --set argument '{pair}' must be FIELD=VALUE format")
                sys.exit(1)
            key, value = pair.split("=", 1)
            field_updates[key] = value

    if not field_updates and not args.clear:
        print("Nothing to do. Provide --set and/or --clear arguments.")
        sys.exit(0)

    update_form(args.input_pdf, args.output_pdf, field_updates, args.clear)


if __name__ == "__main__":
    main()

```

### references/filing-status.md

```markdown
# Filing Status Decision Tree

## Part A: Filer Type (Citizen vs. Resident Alien vs. NRA)

### US Citizen
- Born in the US, or
- Naturalized citizen, or
- Born abroad to US citizen parent(s)
→ **Resident**. File Form 1040.

### Green Card Holder
- Lawful permanent resident at any point during the tax year
→ **Resident**. File Form 1040.
- Note: Even if the green card was surrendered mid-year, you may be a resident for the full year or a dual-status filer.

### Visa Holder — Apply the Substantial Presence Test (SPT)

**Step 1: Check exempt individual status.**
Exempt individuals do NOT count their days toward the SPT:
- F-1 / J-1 **students**: exempt for first **5 calendar years** in the US
- J-1 **teachers/researchers**: exempt for first **2 calendar years**
- Diplomats (A/G visas): exempt indefinitely

If exempt → **NRA** for the exempt period. File Form 1040-NR.

**Step 2: Count days (non-exempt individuals only).**

```
SPT total = (days in current year × 1)
          + (days in 1st prior year × 1/3)
          + (days in 2nd prior year × 1/6)
```

- If SPT total ≥ 183 → **Resident alien**. File Form 1040.
- If SPT total < 183 → **NRA**. File Form 1040-NR.

**Step 3: Closer Connection Exception.**
Even if SPT ≥ 183, you may still be treated as NRA if:
- You were present < 183 days in the current year, AND
- You maintained a tax home in a foreign country, AND
- You had a closer connection to that country
- Must file Form 8840 to claim this exception.

### Dual-Status Filers
If residency status changed mid-year (e.g., F-1 student who became H-1B mid-year and passed SPT):
- File Form 1040 as a dual-status return
- Attach a statement for the NRA portion of the year
- Cannot use standard deduction (must itemize)
- Cannot file MFJ (unless electing to treat NRA spouse as resident for the full year)
- This is a complex case — flag it for the user and suggest professional review

### First-Year Election (IRC §7701(b)(4))
An NRA who doesn't meet SPT can elect to be treated as a resident from a specific date if:
- They were present ≥ 31 consecutive days in the election year, AND
- They were present ≥ 75% of days from the start of that 31-day period through year-end
- Must be a resident in the following year

This is uncommon but comes up when someone arrives mid-year on H-1B.

## Part B: Filing Status (for Form 1040 Filers)

Once determined to be a resident (citizen or RA), choose filing status:

### Single
- Unmarried on Dec 31 of the tax year, OR
- Legally separated under a divorce decree

### Married Filing Jointly (MFJ)
- Married on Dec 31 and both spouses agree to file together
- Generally the most favorable tax brackets and deductions
- Both spouses are jointly liable for the tax

### Married Filing Separately (MFS)
- Married but choosing to file separate returns
- Usually results in higher tax — but useful when:
  - One spouse has significant medical expenses (7.5% AGI floor is lower with lower individual AGI)
  - Income-driven student loan repayment (lower AGI = lower payment)
  - You don't want to be liable for spouse's tax

### Head of Household (HOH)
- Unmarried (or considered unmarried) on Dec 31, AND
- Paid more than half the cost of keeping up a home, AND
- A qualifying person lived with you for more than half the year
- Better brackets than Single; larger standard deduction ($22,500 for 2025)

### Qualifying Surviving Spouse (QSS)
- Spouse died in one of the two prior tax years
- You have a dependent child
- You paid more than half the cost of maintaining the home
- Gets the same standard deduction and brackets as MFJ

## Quick Reference: 2025 Standard Deductions

| Filing Status | Standard Deduction |
|--------------|-------------------|
| Single | $15,000 |
| MFJ | $30,000 |
| MFS | $15,000 |
| HOH | $22,500 |
| QSS | $30,000 |

Add $2,000 if age 65+ or blind (per qualifying condition).

```

### references/form-routing.md

```markdown
# Form Routing: Income Types → Required Forms

Use this table to determine which forms and schedules the user needs based on their source documents and income types. Start from the source docs the user has, then follow the chain.

## Income Routing Table

| Source Doc | Income Type | Goes To | Then Flows To |
|-----------|-------------|---------|---------------|
| W-2 | Wages, salary, tips | 1040 Line 1a | — |
| W-2 Box 12 Code W | Employer HSA contributions | Form 8889 Line 9 | Schedule 1 Line 13 → 1040 Line 10 |
| 1099-NEC | Self-employment income | Schedule C Line 1 | Schedule C Line 31 → Schedule 1 Line 3 → 1040 Line 8; also → Schedule SE |
| 1099-INT | Interest income | Schedule B Part I (if total > $1,500) | 1040 Line 2b |
| 1099-DIV | Ordinary dividends | Schedule B Part II (if total > $1,500) | 1040 Line 3b |
| 1099-DIV Box 1a vs 1b | Qualified dividends | — | 1040 Line 3a (qualified portion, taxed at capital gains rates) |
| 1099-B | Stock/crypto sales | Form 8949 | Schedule D → 1040 Line 7 |
| 1099-MISC Box 1 | Rents | Schedule E Part I | Schedule E → Schedule 1 Line 5 → 1040 Line 8 |
| 1099-MISC Box 2 | Royalties | Schedule E Part I | Schedule E → Schedule 1 Line 5 → 1040 Line 8 |
| 1099-SA | HSA distributions | Form 8889 Part II | Taxable amount → Schedule 1 Line 8c → 1040 Line 8 |
| 5498-SA | HSA contributions | Form 8889 Line 2 | Form 8889 Line 13 → Schedule 1 Line 13 → 1040 Line 10 |
| 1098 | Mortgage interest | Schedule A Line 8a | 1040 Line 13 (if itemizing) |
| 1098-T | Tuition | Form 8863 | 1040 Line 29 (AOTC) or Schedule 3 Line 3 (LLC) |
| 1099-G Box 1 | Unemployment compensation | — | 1040 Line 7 |
| 1099-R | Retirement distributions | — | 1040 Lines 4a/4b (IRA) or 5a/5b (pensions) |

## Schedule Trigger Rules

These rules determine when each schedule is required:

### Always Required if Applicable
| Schedule | Required When |
|----------|--------------|
| Schedule 1 | Any additional income (1099-NEC, HSA, etc.) or above-the-line adjustments |
| Schedule 2 | AMT, excess premium tax credit, SE tax, or additional Medicare tax |
| Schedule 3 | Education credits, foreign tax credit, estimated tax payments, excess SS withholding |

### Conditional Schedules
| Schedule | Required When |
|----------|--------------|
| Schedule A | Itemizing deductions (total > standard deduction) |
| Schedule B | Interest or dividends > $1,500 |
| Schedule C | Self-employment / sole proprietor income |
| Schedule D | Capital gains or losses from investments |
| Schedule E | Rental income, royalties, partnership/S-corp income |
| Schedule SE | Net self-employment income ≥ $400 |

### Additional Forms
| Form | Required When |
|------|--------------|
| Form 8949 | Stock/crypto sales (detail behind Schedule D) |
| Form 8889 | HSA contributions, distributions, or employer contributions |
| Form 8863 | Education credits (AOTC or Lifetime Learning) |
| Schedule 8812 | Child tax credit (if children under 17) |
| Form 2441 | Child and dependent care expenses credit |
| Form 8959 | Additional Medicare Tax (wages > $200K single / $250K MFJ) |
| Form 8960 | Net Investment Income Tax (MAGI > $200K single / $250K MFJ) |

## NRA-Specific Forms

If the filer is a nonresident alien, the form set is different. See `references/form-field-maps.md` for field-to-line mappings and the NRA workflow in the main SKILL.md Step 3b.

| Form | Purpose | Key Trigger |
|------|---------|-------------|
| Form 1040-NR | Main NRA return (replaces Form 1040) | Always required for NRA filers |
| Form 8843 | Exempt individual statement | F-1/J-1 students claiming SPT exemption |
| Schedule NEC | Non-effectively connected income | Dividends, capital gains at flat rate (not ECI) |
| Schedule OI | Other information | Visa type, treaty claims, days present |
| Form 8833 | Treaty-based return position disclosure | Claiming any treaty benefit (e.g., Article 20(c)) |
| Schedule 1 | Additional income/adjustments | Contractor income (1099-NEC), HSA deduction |
| Form 8889 | HSA | HSA contributions or distributions |

## Decision Shortcuts

- **Only W-2 income, no other complexity** → Form 1040 only (no schedules needed). Standard deduction.
- **W-2 + bank interest under $1,500** → Form 1040 only. Interest goes directly on Line 2b.
- **W-2 + 1099-NEC** → Form 1040 + Schedule C + Schedule SE + Schedule 1 + Schedule 2
- **W-2 + stock sales** → Form 1040 + Form 8949 + Schedule D
- **W-2 + HSA** → Form 1040 + Form 8889 + Schedule 1

```

### references/common-schedules.md

```markdown
# Common Schedules — Key Fields and Pitfalls

Field-level guidance for the most frequently used citizen/RA schedules. This is not exhaustive — it covers the fields where mistakes most commonly happen.

For NRA-specific form fields (1040-NR, 8843, Schedule NEC/OI, 8833), see `references/form-field-maps.md` in this skill.

## Form 1040 — Key Lines

| Line | Description | Source |
|------|-------------|--------|
| 1a | Wages, salaries, tips | Sum of all W-2 Box 1 |
| 2a | Tax-exempt interest | 1099-INT Box 8 |
| 2b | Taxable interest | 1099-INT Box 1 |
| 3a | Qualified dividends | 1099-DIV Box 1b |
| 3b | Ordinary dividends | 1099-DIV Box 1a |
| 7 | Capital gain or loss | Schedule D Line 16 (or Line 21 if using worksheet) |
| 8 | Other income from Schedule 1 | Schedule 1 Line 11 |
| 9 | Total income | Sum of Lines 1z through 8 |
| 10 | Adjustments from Schedule 1 | Schedule 1 Line 26 |
| 11 | AGI | Line 9 - Line 10 |
| 13 | Deductions | Standard deduction or Schedule A Line 17 |
| 15 | Taxable income | Line 11 - Line 13 - Line 14 |
| 16 | Tax | From tax table, Qualified Dividends worksheet, or Schedule D worksheet |
| 24 | Total tax | After credits and other taxes |
| 25a | Federal tax withheld from W-2s | Sum of all W-2 Box 2 |
| 33 | Total payments | |
| 34 | Overpayment (refund) | Line 33 - Line 24 |
| 37 | Amount owed | Line 24 - Line 33 |

**Common errors**: Forgetting to sum multiple W-2s for Line 1a. Missing Line 7 when Schedule D applies. Putting adjustments on Line 8 instead of Line 10.

## Schedule C — Profit or Loss from Business

| Line | Description | Notes |
|------|-------------|-------|
| 1 | Gross receipts | Sum of 1099-NEC amounts |
| 7 | Gross income | Line 1 - returns/allowances - COGS |
| 8-27 | Expenses | Business expenses (categorized) |
| 28 | Total expenses | |
| 31 | Net profit or loss | Line 7 - Line 28 → goes to Schedule 1 Line 3 |

**Common errors**:
- Including personal expenses as business expenses
- Forgetting the home office deduction (simplified: $5/sq ft, max 300 sq ft = $1,500)
- Not separating meals (50% deductible) from other expenses

## Schedule SE — Self-Employment Tax

| Line | Description | Notes |
|------|-------------|-------|
| 2 | Net earnings | From Schedule C Line 31 (or combined if multiple Sch C's) |
| 4 | 92.35% of Line 2 | Only 92.35% of net earnings are subject to SE tax |
| 12 | SE tax | 15.3% of Line 4 (12.4% Social Security up to $176,100 for 2025 + 2.9% Medicare) |
| 13 | Deductible part of SE tax | 50% of Line 12 → Schedule 1 Line 15 |

**Critical**: SE tax applies when net self-employment income ≥ $400. This is separate from income tax — many first-time freelancers miss it entirely.

**Common errors**:
- Forgetting to file Schedule SE at all
- Not taking the 50% SE tax deduction on Schedule 1 (it's above the line, reducing AGI)
- Applying the Social Security wage cap incorrectly when the filer also has W-2 wages

## Schedule D — Capital Gains and Losses

| Line | Description | Notes |
|------|-------------|-------|
| 1b | Short-term from Form 8949 Box A | Reported to IRS, basis reported |
| 2 | Short-term from Form 8949 Box B | Reported to IRS, basis NOT reported |
| 3 | Short-term from Form 8949 Box C | NOT reported to IRS |
| 7 | Net short-term gain/loss | Sum of Lines 1-6 |
| 8b | Long-term from Form 8949 Box D | Reported, basis reported |
| 9 | Long-term from Form 8949 Box E | Reported, basis NOT reported |
| 10 | Long-term from Form 8949 Box F | NOT reported |
| 15 | Net long-term gain/loss | Sum of Lines 8-14 |
| 16 | Combined | Line 7 + Line 15 → 1040 Line 7 |

**Common errors**:
- Using proceeds as gain (forgetting to subtract cost basis)
- Not adjusting for wash sales (1099-B Box 1g)
- Ignoring the **$3,000 loss limit** — net losses over $3,000 carry forward to next year
- Mixing short-term and long-term transactions in the wrong Form 8949 box

## Schedule A — Itemized Deductions

Only file if total exceeds the standard deduction.

| Line | Description | Cap/Limit |
|------|-------------|-----------|
| 1-4 | Medical expenses | Only amount exceeding 7.5% of AGI |
| 5a | State/local income tax | SALT cap: $10,000 total ($5,000 MFS) |
| 5b | State/local sales tax | Alternative to 5a (choose one) |
| 5c | Real estate taxes | Included in SALT cap |
| 8a | Home mortgage interest | On up to $750K of debt ($375K MFS) |
| 11-14 | Gifts to charity | Cash: up to 60% of AGI. Property: up to 30% of AGI. |
| 17 | Total itemized deductions | → 1040 Line 13 |

**Common errors**:
- Exceeding the $10,000 SALT cap without realizing it
- Deducting mortgage interest on a home equity loan used for non-home purposes (not deductible post-TCJA)
- Claiming charitable contributions without proper documentation (receipts for $250+)

## Schedule B — Interest and Dividends

Required when interest or dividends exceed $1,500.

| Part | Lines | Source |
|------|-------|--------|
| I | Lines 1-4 | List each payer and interest amount from 1099-INT |
| II | Lines 5-6 | List each payer and dividend amount from 1099-DIV |

**Common errors**: Forgetting to include interest from multiple bank accounts. Not reporting tax-exempt interest separately (it goes on 1040 Line 2a, not Schedule B).

## Form 8889 — HSA

| Line | Description | Source |
|------|-------------|--------|
| 2 | HSA contributions you made | 5498-SA Box 2 minus employer contributions |
| 9 | Employer contributions | W-2 Box 12 Code W |
| 13 | HSA deduction | Line 2 - excess over limit → Schedule 1 Line 13 |
| 14a | Total distributions | 1099-SA Box 1 |
| 15 | Distributions for medical expenses | (user must track this) |
| 17a | Taxable HSA distributions | If 14a > 15 |

**2025 contribution limits**: $4,300 (self-only), $8,550 (family). Add $1,000 if 55+.

**Common errors**:
- Double-counting employer contributions (W-2 Code W already includes them — don't add again on Line 2)
- Not filing Form 8889 when you have an HSA — it's required even if you made no contributions, as long as you had a balance
- Forgetting the 20% penalty on non-medical distributions under age 65

```

### references/form-field-maps.md

```markdown
# IRS Form Field-to-Line Mappings

Field names extracted from 2025 IRS fillable PDFs. Field name pattern is typically `topmostSubform[0].PageN[0].f{page}_{seq}[0]`.

> **Important**: These mappings were determined by Y-position analysis of annotation Rect coordinates. Always verify against the actual PDF if using a different tax year — field numbering can change between years.

## Form 1040-NR

### Page 1 (Key Income Lines)

| Field | Y-pos | Line | Description |
|-------|-------|------|-------------|
| f1_42 | ~384 | 1a | Wages, salaries, tips (W-2 Box 1) |
| f1_43 | ~372 | 1b | Household employee income |
| f1_44 | ~360 | 1c | Tip income not on 1a |
| f1_45 | ~348 | 1d | Medicaid waiver |
| f1_46 | ~336 | 1e | Dependent care benefits |
| f1_47 | ~324 | 1f | Adoption benefits |
| f1_48 | ~312 | 1g | Form 8919 wages |
| f1_50 | ~300 | 1h | Other earned income |
| f1_53 | ~252 | 1k | Treaty-exempt income (e.g. $5000 Art. 20(c)) |
| f1_54 | ~240 | 1z | Total (sum of 1a through 1h, or 1a minus 1k depending on instruction) |
| f1_55 | ~228 | 2a | Tax-exempt interest |
| f1_56 | ~216 | 2b | Taxable interest |
| f1_57 | ~204 | 3a | Qualified dividends |
| f1_58 | ~192 | 3b | Ordinary dividends |
| f1_62 | ~168 | 5a | Pensions/annuities |
| f1_63 | ~168 | 5b | Pensions taxable (different X from 5a) |
| f1_65 | ~144 | 6 | Reserved for future use — LEAVE EMPTY |
| f1_66 | ~132 | 7a | Capital gain/loss |
| f1_68 | ~108 | 8 | Additional income from Schedule 1 |
| f1_69 | ~96 | 9 | Total effectively connected income |
| f1_70 | ~72 | 10 | Adjustments from Schedule 1 |
| f1_71 | ~60 | 11a | Adjusted gross income |

### Page 2 (Tax Computation and Payments)

| Field | Line | Description |
|-------|------|-------------|
| f2_01 | 11b | AGI from page 1 |
| f2_03 | 12 | Itemized deductions |
| f2_07 | 15 | Taxable income |
| f2_09 | 16 | Tax |
| f2_11 | 18 | Tax after credits |
| f2_15 | 22 | Other taxes |
| f2_16 | 23a | Tax on income not effectively connected (Schedule NEC) |
| f2_19 | 23d | Total NEC tax |
| f2_20 | 24 | Total tax (Line 22 + Line 23d) |
| f2_21 | 25a | Federal tax withheld (W-2 Box 2) |
| f2_35 | 33 | Total payments |
| f2_36 | 34 | Overpayment |
| f2_37 | 35a | Refund amount |

### Common Errors to Watch

- **f1_50 (Line 1h)**: Often gets a duplicate of wages. Should only have "other earned income" not reported elsewhere.
- **f1_63 (Line 5b)**: Contractor income sometimes lands here. Contractor income goes on Schedule 1 → Line 8.
- **f1_65 (Line 6)**: Reserved line. Must be empty. AGI sometimes gets placed here by mistake.
- **f1_53 (Line 1k)**: Often left blank when treaty exemption applies. Must show treaty amount if Form 8833 is filed.
- **f1_71 (Line 11a)**: Often left blank. Must have AGI.

## Form 8843

Field name pattern: `topmostSubform[0].Page1[0].f1_XX[0]`

| Field | Line | Description |
|-------|------|-------------|
| f1_04 | 1a (First) | First name |
| f1_05 | 1a (Last) | Last name |
| f1_06 | 1b | SSN or ITIN |
| f1_07 | - | Country of nationality |
| f1_08 | - | US address |
| f1_09 | - | Date of entry (MM/DD/YYYY) |
| f1_10 | 2 | Visa type and status |
| f1_11 | 3a | Country of tax residence |
| f1_12 | 3a | Country of citizenship |
| f1_13 | 3b | Passport number |
| f1_14 | 4a (current) | Days present current year |
| f1_15 | 4a (prior 1) | Days present 1st prior year |
| f1_16 | 4a (prior 2) | Days present 2nd prior year |
| f1_17 | 4b | Days of current year to exclude from substantial presence test |
| f1_26 | Part III, 8a | University/institution name and location |
| f1_27 | Part III, 8b | Director of academic program name and address |
| f1_28 | Part III, 9a | Current nonimmigrant status |
| f1_32 | Part III, 10a | Prior year 1 status |
| f1_33 | Part III, 10a | Prior year 2 status |

### Checkboxes
| Field | Value | Meaning |
|-------|-------|---------|
| c1_2[1] | /2 | "Yes" for question about immigration status change |
| c1_3[1] | /2 | "Yes" for teacher/trainee question (varies by form version) |

### Critical Rule
**Line 4b must equal the days in Line 4a (current year)**. Common error: setting 4b to 365 when the person was only present for fewer days (e.g., 338 if they departed before year-end).

## Schedule NEC

Field name pattern: `form1040-NR[0].Page1[0].Table_NatureOfIncome[0].LineXX[0].f1_XX[0]`

Organized by income type rows and columns (nature, country, rate, amount, tax):

| Income Type | Line | Amount Field | Rate Field | Tax Field |
|-------------|------|-------------|------------|-----------|
| Dividends | 2 | amount column | rate column | tax column |
| Capital gains | 7 | amount column | rate column | tax column |
| Total | 12 | - | - | total NEC tax |

Rates for US-China Treaty:
- Dividends: 10% (Article 9(2))
- Capital gains: 30% (IRC 871(a)(2), no treaty reduction)
- Interest from bank deposits: EXEMPT (IRC 871(i)(2)(A)) — do not report

## Schedule OI (Other Information)

Key fields for days-of-presence and treaty claims. Field names vary but critical data:

| Question | Content |
|----------|---------|
| Visa type | Current nonimmigrant visa (e.g., F-1) |
| Country | Country of citizenship and tax residence |
| Days present | Current year, 1st prior, 2nd prior (must match Form 8843) |
| Treaty claim | Article number and country |
| Departure date | Date of last departure if applicable |

## Form 8833 (Treaty-Based Return Position)

Key fields:
- Treaty country (e.g., China)
- Treaty article (e.g., Article 20(c))
- IRC provision (e.g., IRC 871(b))
- Exemption amount (e.g., $5,000)
- Explanation of treaty position

## Form 8889 (HSA)

Key fields:
- Line 2: HSA contributions (from 5498-SA Box 2 minus employer contributions)
- Line 9: Employer contributions (W-2 Code W)
- Line 13: HSA deduction (Line 2 minus Line 9, or limited amount)

Note: For NRA filers, HSA rules can be complex if presence spans multiple countries. Verify eligibility for months of US residency.

## Schedule 1 (Additional Income and Adjustments)

Key fields for NRA:
- Part I, Line 8h (or appropriate sub-line): Other income (contractor/1099-NEC income)
- Part I, Line 10: Total additional income → flows to 1040-NR Line 8
- Part II, Line 13: HSA deduction (from Form 8889)
- Part II, Line 26: Total adjustments → flows to 1040-NR Line 10

```

### references/pypdf-recovery.md

```markdown
# pypdf PDF Recovery Procedures

## Understanding PDF Form Architecture

A fillable PDF stores form data in two parallel structures:

1. **AcroForm /Fields** — a tree in the document catalog (`/Root → /AcroForm → /Fields`). This is what `get_form_text_fields()` and `get_fields()` read from.
2. **Page /Annots** — an array on each page containing the visual widget annotations. Each annotation has `/T` (field name), `/V` (value), `/FT` (field type), and `/Rect` (position).

Normally these reference the same objects. Corruption can break the linkage.

## Diagnosing Corruption

### Symptom: `get_form_text_fields()` returns empty but the PDF looks fine in a viewer

```python
reader = PdfReader("corrupted.pdf")

# Check 1: Are AcroForm /Fields empty?
catalog = reader.trailer["/Root"]
acroform = catalog.get("/AcroForm")
if acroform:
    af = acroform.get_object()
    fields = af.get("/Fields", [])
    print(f"AcroForm /Fields count: {len(fields)}")  # If 0 = broken field tree

# Check 2: Do page annotations still have values?
page = reader.pages[0]
annots = page.get("/Annots")
if annots:
    for annot_ref in annots:
        annot = annot_ref.get_object()
        t = str(annot.get("/T", ""))
        v = annot.get("/V", "")
        if v:
            print(f"Annotation {t} has value: {v}")  # Values survive here
```

If Check 1 shows 0 fields but Check 2 shows values, the field tree is broken but data is recoverable.

## Recovery: Rebuild Field Tree from Annotations

```python
from pypdf import PdfReader, PdfWriter
from pypdf.generic import NameObject, TextStringObject, ArrayObject

reader = PdfReader("corrupted.pdf")
writer = PdfWriter()
writer.append(reader)

# Optional: update specific field values during recovery
target_updates = {"f1_17": "338"}  # example: fix a value while rebuilding

# Step 1: Update annotation values on writer pages
for page_idx in range(len(writer.pages)):
    page = writer.pages[page_idx]
    annots = page.get("/Annots")
    if not annots:
        continue
    for annot_ref in annots:
        annot = annot_ref.get_object()
        t = str(annot.get("/T", ""))
        for key, val in target_updates.items():
            if key in t:
                annot[NameObject("/V")] = TextStringObject(val)

# Step 2: Collect all annotation references across all pages
all_field_refs = []
for page_idx in range(len(writer.pages)):
    page = writer.pages[page_idx]
    annots = page.get("/Annots")
    if annots:
        for annot_ref in annots:
            all_field_refs.append(annot_ref)

# Step 3: Rebuild AcroForm /Fields
catalog = writer._root_object
acroform = catalog.get("/AcroForm")
if acroform:
    af_obj = acroform.get_object() if hasattr(acroform, 'get_object') else acroform
    af_obj[NameObject("/Fields")] = ArrayObject(all_field_refs)

# Step 4: Write to DIFFERENT path, then copy
output_path = "/tmp/recovered.pdf"
with open(output_path, "wb") as f:
    writer.write(f)

# Step 5: Verify
reader2 = PdfReader(output_path)
fields = reader2.get_form_text_fields()
print(f"Recovered {len(fields)} text fields")
all_f = reader2.get_fields()
print(f"Recovered {len(all_f)} total fields (incl. checkboxes)")
```

## Root Cause: Writing to Same File Path

The most common cause of field tree corruption is writing pypdf output to the same file being read:

```python
# This WILL corrupt the file
reader = PdfReader("form.pdf")
writer = PdfWriter()
writer.append(reader)
# ... modifications ...
with open("form.pdf", "wb") as f:  # SAME PATH as reader input
    writer.write(f)
```

What happens: `PdfReader` uses lazy reading. When `writer.write()` opens the same file for writing, it truncates the file while the reader still has references into it. The page annotations (already in memory) survive, but the AcroForm catalog gets corrupted during the partial read/write overlap.

**Prevention**: Always write to a temp file first:
```python
import shutil
with open("/tmp/form_temp.pdf", "wb") as f:
    writer.write(f)
shutil.copy("/tmp/form_temp.pdf", "form.pdf")
```

## Other pypdf Gotchas

### `auto_regenerate=True` (the default) clears appearance streams
Always pass `auto_regenerate=False` to `update_page_form_field_values()`. The default `True` removes `/AP` (appearance) entries, which makes some PDF viewers show blank fields even though `/V` has a value.

### "No fields to update on this page" warning
This is normal and harmless. It just means the field names you passed don't exist on that particular page. Since we iterate all pages, this fires for pages that don't contain the target fields.

### Field names include full path
IRS PDFs use hierarchical field names like `topmostSubform[0].Page1[0].f1_42[0]`. When using `update_page_form_field_values()`, you need the FULL path, not just `f1_42`. Extract the full name from `get_form_text_fields()` or from annotations.

### Checkbox values
IRS checkboxes use `/Off` for unchecked and a number like `/1`, `/2`, `/Yes` for checked. The specific "on" value varies by form. Check the existing value in the annotation before trying to set it.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "irreel",
  "slug": "tax-filing",
  "displayName": "tax-filing",
  "latest": {
    "version": "0.2.0",
    "publishedAt": 1772653591194,
    "commit": "https://github.com/openclaw/skills/commit/2ffc288d7986607762da78e7c4830cb395c44dd0"
  },
  "history": []
}

```