Form 1040 Review

Overview

Run a structured review of normalized Form 1040 data for the latest tax year in the provided set. Produce three artifacts: a detailed findings JSON file, a markdown summary, and a separate DOCX risk report listing major items and related risks.

Quick Start

1. Prepare normalized input JSON using references/input_schema.json.
2. Confirm current-law parameters in references/current_tax_law_2025.json before use.
3. Run:

python scripts/review_1040.py --input <normalized_returns.json> --output-dir output/form-1040-review

4. Review outputs:

• review_summary.md
• review_findings.json
• form-1040-risk-report.docx

Workflow

1. Identify the current return

• Select the highest tax_year in the input as the current return.
• Treat all prior years as historical comparison returns.

2. Run current-year law checks

• Validate internal arithmetic and line-to-line relationships.
• Compare major current-year items to law parameters:
• Standard deduction by filing status and age/blind additions.
• Regular-rate tax computation when no preferential income is present.
• Child Tax Credit and ACTC limits.
• Self-employment tax and Additional Medicare tax thresholds.

3. Run multi-year consistency checks

• Compare current return against the most recent prior year.
• Flag large year-over-year movement in wages, AGI, taxable income, credits, payments, and refund/amount owed.
• Flag filing-status and dependent-count shifts for explanation.

4. Produce risk outputs

• Generate a structured findings file (review_findings.json).
• Generate a human-readable summary (review_summary.md).
• Generate a standalone DOCX risk register (form-1040-risk-report.docx) that lists each major item, severity, observations, and recommended documentation.
• Produce an audit-likelihood estimate based on weighted findings and return complexity.

Inputs

Use the normalized schema in references/input_schema.json. At minimum, include:

• tax_year
• filing_status
• major_items for core 1040 lines (AGI, deduction, taxable income, tax, payments, refund/amount owed)

Use references/major_items_reference.md for canonical key mapping.

Law Source Discipline

• Update references/current_tax_law_2025.json when the filing year changes or IRS issues revisions.
• Use only official IRS/SSA sources for numeric thresholds.
• If law data is older than the analyzed return year, flag the result as stale and require manual update before final sign-off.

Script

scripts/review_1040.py performs:

• Current-year arithmetic and law checks.
• Prior-year consistency checks.
• Weighted audit-risk scoring.
• DOCX risk report generation with python-docx.

If python-docx is missing, install it:

python -m pip install --user python-docx