Tax Organizer for Personal & Consultant

Organizes and processes personal tax documents to generate accurate, tax reports and drafts. Use when user uploads or describes tax forms (W-2, 1099s, K-1s, 1098), mentions rental properties, royalties, partnerships/S-corps, business expenses, donations, or needs Schedule E drafts. Handles complex income sources, expense matching, per diem optimization, and charitable receipt identification.

When to Use

• Organizing personal and consultant tax documents
• Processing rental property expenses, income, and depreciation
• Matching business trip expenses with per diem optimization
• Generating tax-ready XLS reports for accountant review
• Classifying W-2s, 1099s, and donation receipts
• Tracking incremental document additions across multiple sessions

Usage

Navigate to your tax year folder and run this skill.
Drop documents anytime — the skill detects new files and only processes what's changed.

Folder Structure

The skill expects and creates this layout in the working directory:

Tax-2025/
├── README.md                     # Global config + instructions
├── Rental-123-Main-St/
│   ├── README.md                 # Business config (see template below)
│   └── (drop receipts/invoices here)
├── Freelance-Consulting/
│   ├── README.md
│   └── ...
├── W2s/                          # W-2 forms
├── 1099s/                        # All 1099 variants
├── Donations/                    # Charitable contribution receipts
├── Unclassified/                 # Files the skill couldn't classify
├── Reports/                      # Generated XLS outputs
└── .processed-files.log          # Internal: tracks processed files

Special folders

• W2s/

  — W-2 forms. Organized for reference (Form 1040, not Schedule E).

• 1099s/

  — All 1099 variants (NEC, MISC, INT, DIV, K-1, etc.).

• Donations/

  — Charitable contribution receipts (Form 8283 / Schedule A).

• Unclassified/

  — Documents that couldn't be auto-classified. Flagged for manual review.

• Reports/

  — Generated XLS report files. Regenerated on every run.

Root README.md Template

When no root

README.md

# Tax Documents — {{TAX_YEAR}}

## Instructions

This folder organizes your tax documents for the {{TAX_YEAR}} tax year.

### How to use

1. **Drop receipts and documents** into the tax year folder
   — or into any existing business subfolder
2. **Run the skill** — it scans your documents, identifies business
   lines, and guides you through setup
3. **Add more documents anytime** — the skill detects new files and
   only processes what's changed

### Special folders

- `W2s/` — Drop W-2 forms here (organized for reference)
- `1099s/` — Drop all 1099 forms here
- `Donations/` — Drop charitable contribution receipts here

## Filing Information

- **Tax Year**: {{TAX_YEAR}}
- **Filing Status**: {{FILING_STATUS}}
- **Preparer**: {{PREPARER_NAME}}

Business README.md Template

Each business folder gets a

README.md

# {{BUSINESS_NAME}}

## Business Information

- **Type**: {{BUSINESS_TYPE}}
- **EIN**: {{EIN}}
- **Address**: {{ADDRESS}}
- **Ownership**: {{OWNERSHIP_PERCENTAGE}}%

## Property Details

<!-- Only for rental properties -->

- **In-Service Date**: {{IN_SERVICE_DATE}}
- **Cost Basis**: ${{COST_BASIS}}
- **Land Value**: ${{LAND_VALUE}}
- **Depreciation Method**: {{DEPRECIATION_METHOD}}

## Business Trips

<!-- List trips related to this business. The skill will auto-match
     expenses (flights, hotels, meals, taxi, conference fees) that
     fall within these date ranges. -->

### {{TRIP_NAME}} — {{TRIP_DESTINATION}}

- **Dates**: {{TRIP_START}} – {{TRIP_END}}
- **Purpose**: {{TRIP_PURPOSE}}

## Important Events

<!-- Note major events that affect tax treatment -->

- **{{EVENT_DATE}}**: {{EVENT_DESCRIPTION}}

## Notes

<!-- Any additional notes for your records or your accountant -->

Business types: Residential Rental, Commercial Rental, Royalties, Partnership (K-1), S-Corp (K-1), Freelance/Self-Employment, Farm Rental

Depreciation methods:

• Residential rental: Straight-line over 27.5 years
• Commercial rental: Straight-line over 39 years
• Include mid-month convention for the placed-in-service year

Incremental Processing

The skill maintains a

.processed-files.log

# Tax Organizer — Processed Files Log
# Format: SHA256_HASH | ORIGINAL_PATH | ORGANIZED_PATH | TIMESTAMP
a1b2c3d4... | ./invoice_march.pdf | ./Rental-123-Main-St/2024-03-15 Plumber Co - Repairs - Pipe fix.pdf | 2024-12-01T10:30:00
e5f6g7h8... | ./receipt.jpg | ./Rental-123-Main-St/2024-04-20 Home Depot - Supplies - Door hardware.jpg | 2024-12-01T10:30:00

Processing rules

On each run, hash all files in the directory tree (excluding

Reports/

.processed-files.log

Report to user: "Found X new files, Y duplicates, Z already processed"

Workflow

Execute these 9 steps in order:

Step 1: Scan & Discover

1. Scan the working directory recursively for all documents: PDF, JPG, PNG, JPEG, TIFF, XLS, XLSX, CSV, EML, MSG. For XLS/XLSX files, use the

   /xlsx

   skill to read their contents.
2. Exclude

   Reports/

   folder and

   .processed-files.log

3. Compute SHA-256 hash for each file found
4. Load

   .processed-files.log

   if it exists
5. Categorize every file as: new, already-processed, duplicate, or moved/renamed (see Processing Rules above, use mv instead of cp)
6. Detect existing

   README.md

   configs in business folders
7. Report to user:
   • Total files found
   • New files to process
   • Duplicates found
   • Already processed (skipped)
   • File types breakdown

If there are zero new files to process, skip to Step 8 (regenerate reports) or inform the user and stop.

Step 2: Interactive Business Setup

First run (no root

README.md

1. Ask user for:
   • Tax year
   • Filing status (Single, Married Filing Jointly, Married Filing Separately, Head of Household, Qualifying Surviving Spouse)
   • Preparer name (their name or accountant's name)
2. Generate the root

   README.md

   using the template above
3. Create empty special folders:

   W2s/

   ,

   1099s/

   ,

   Donations/

   ,

   Unclassified/

   ,

   Reports/

4. Analyze the new documents found in Step 1 and identify likely business lines:
   • Property addresses on invoices/receipts → suggest a rental or commercial property folder
   • Payer names on 1099-NEC/MISC → suggest a freelance or royalty folder
   • K-1 forms → suggest a Partnership or S-Corp folder
   • Group documents that share an address or entity name into a single proposed business
5. Present the suggested business lines to the user, for example:

   I found documents referencing these potential business lines:
   
   1. "456 Oak Ave" — appears on 3 receipts and a 1098. Looks like a rental property.
   2. "Acme Consulting LLC" — appears on a 1099-NEC. Looks like freelance income.
   
   For each one I'll ask a few questions to set it up.
   

6. For each confirmed business line, ask:
   • Business name (suggest one based on address or entity name)
   • Business type (Residential Rental, Commercial Rental, Royalties, Partnership, S-Corp, Freelance/Self-Employment, Farm Rental)
   • EIN (if applicable)
   • Address (pre-fill from document if found)
   • Ownership percentage
   • For rentals: in-service date, cost basis, land value, depreciation method
7. For each business, ask if there were any related business trips:
   • Trip name, destination, date range, purpose
8. Generate a

   README.md

   in each business folder using the template above
9. If any documents don't suggest a clear business line, ask the user whether to create a new business folder or place them in

   Unclassified/

Subsequent runs (root

README.md

1. Parse existing

   README.md

   configs from root and all business folders
2. If new documents suggest a business line not covered by any existing folder, prompt the user to set it up (same flow as steps 4–9 above, for the new business only)
3. Do NOT re-prompt for existing businesses unless user explicitly requests changes
4. Proceed to Step 3

Step 3: Document Classification

For each new/unprocessed document, read and classify it:

W2s/

1099s/

1099s/

1099s/

1099s/

1099s/

1099s/

1099s/

1099s/

1099s/

1099s/

Donations/

Unclassified/

Classification logic for business expenses:

1. Check if the document mentions a property address matching a business folder
2. Check if the vendor name appears in previous documents for a business
3. Check if the expense date falls within a business trip date range
4. If multiple businesses could match, ask the user
5. If no match found, place in

   Unclassified/

Step 4: Extract Information

For each document, extract all relevant data fields:

All documents:

• Date (transaction date, statement date, or tax year)
• Vendor / payer name
• Amount(s)
• Description / memo

W-2 fields:

• Employer name and EIN
• Employee name and SSN (last 4 only — do not store full SSN)
• Box 1: Wages, tips, other compensation
• Box 2: Federal income tax withheld
• Box 3: Social security wages
• Box 4: Social security tax withheld
• Box 5: Medicare wages
• Box 6: Medicare tax withheld
• Box 12 codes (DD, W, etc.)
• Box 13: Statutory employee, retirement plan, third-party sick pay
• State wages and withholding

1099 fields (varies by type):

• Payer name, TIN
• Recipient name
• All box amounts relevant to the 1099 type
• State tax withheld if applicable

Expense fields:

• Vendor name
• Transaction date
• Amount (pre-tax, tax, total)
• Expense category (map to Schedule E line — see line reference table)
• Payment method if visible
• Property/business reference if visible

Donation fields:

• Organization name
• Date of contribution
• Amount (or fair market value for non-cash)
• Cash vs. non-cash
• 501(c)(3) status / tax-exempt confirmation
• Description of donated items (non-cash)
• Whether goods/services were received in return

Spreadsheet files (XLS/XLSX):

• Invoke the

  /xlsx

  skill to read and extract data from Excel files
• These may contain multiple transactions (bank statements, property management reports, accounting exports)
• Extract each row as a separate transaction with the fields above
• CSV files can be read directly without the

  /xlsx

  skill

When extraction is incomplete:

• Use filename clues (dates in filename, vendor name patterns)
• Use file metadata (creation date, modification date)
• Flag incomplete extractions — never silently guess missing values
• Mark confidence level: HIGH (clear document), MEDIUM (partial info), LOW (mostly inferred)

Step 5: Business Trip Expense Matching

1. Parse trip date ranges from each business folder's

   README.md

   :
   • Extract trip name, destination city + state, start date, end date, purpose
2. For each expense document dated within a trip's date range, check if it matches trip-related categories:
   • Airfare / flights
   • Hotels / lodging
   • Meals (50% deductible per IRS rules)
   • Taxi / rideshare / car rental
   • Conference / registration fees
   • Parking and tolls
   • Baggage fees
3. Also check expenses ±1 day outside trip dates — flag as "potentially trip-related" for user review
4. Look up GSA per diem rates for the trip destination:
   • Use the GSA per diem API or published rates for the tax year
   • Lodging rate (per night)
   • M&IE rate (meals and incidental expenses per day)
   • First and last day of travel: 75% of M&IE rate
5. Calculate per diem totals:
   • Lodging: nightly rate × number of nights
   • M&IE: full-day rate × (trip days − 2) + 75% rate × 2 (first/last day)
   • If trip is 1 day: 75% of M&IE, no lodging
6. Compare actual tracked expenses vs. per diem allowance
7. Recommend whichever method produces the larger deduction, noting:
   • Per diem: simpler, no receipt tracking needed for meals
   • Actual: may be higher for expensive destinations
   • IRS requires consistency within a trip (can't mix methods)
8. Tag matched expenses with trip name for reporting

Step 6: Rename & Organize Files

1. Generate a rename/organize plan for all new files. Naming convention:

   YYYY-MM-DD Vendor - Category - Description.ext
   

   Examples:

   • 2024-03-15 Plumber Co - Repairs - Kitchen pipe fix.pdf

   • 2024-04-20 Home Depot - Supplies - Door hardware.jpg

   • 2024-01-31 Acme Corp - W2 - Wages.pdf

   • 2024-12-15 Red Cross - Donation - Annual gift.pdf

   • 2024-09-06 Marriott - Travel - BiggerPockets Conference hotel.pdf

2. Show the complete before/after plan to the user:

   File Organization Plan:
   
   NEW FILES (5):
   ├── invoice_march.pdf
   │   → Rental-123-Main-St/2024-03-15 Plumber Co - Repairs - Pipe fix.pdf
   ├── receipt.jpg
   │   → Rental-123-Main-St/2024-04-20 Home Depot - Supplies - Door hardware.jpg
   ├── W2_acme.pdf
   │   → W2s/2024-01-31 Acme Corp - W2 - Wages.pdf
   ...
   
   DUPLICATES (1):
   ├── invoice_march_copy.pdf (same as invoice_march.pdf) — SKIPPED
   
   UNCLASSIFIED (1):
   ├── mystery_doc.pdf → Unclassified/mystery_doc.pdf — NEEDS REVIEW
   

3. Wait for user approval before executing any file operations

4. Copy files to their organized locations (preserve originals)

5. Update

   .processed-files.log

   with entries for each processed file:

   SHA256_HASH | ORIGINAL_PATH | ORGANIZED_PATH | ISO_TIMESTAMP
   

Step 7: Calculate Depreciation

For each rental property with property details in its

README.md

1. Depreciable basis = Cost Basis − Land Value
2. Annual depreciation:
   • Residential (27.5 years): Depreciable Basis ÷ 27.5
   • Commercial (39 years): Depreciable Basis ÷ 39
3. Mid-month convention (placed-in-service year):
   • Month placed in service: count as half-month
   • Formula: (Annual Depreciation ÷ 12) × (12 − month placed in service + 0.5)
   • Example: Placed in service June 15 → (Annual ÷ 12) × (12 − 6 + 0.5) = 6.5 months
4. Current year depreciation:
   • If placed in service in the current tax year → use mid-month convention
   • If placed in service in a prior year → full annual depreciation
   • If disposed of during the year → mid-month convention for disposal month
5. Output the depreciation amount as Schedule E Line 18 for each property
6. Show calculation details to user:

   Depreciation — 123 Main St:
     Cost Basis:        $285,000
     Land Value:       −$ 60,000
     Depreciable Basis: $225,000
     Method:            27.5-year straight-line (residential)
     In-Service:        2019-06-15
     Years in Service:  5.5 (full year)
     Annual Depr:       $  8,181.82
     2024 Deduction:    $  8,181.82 (Line 18)
   

Step 8: Generate Reports

Generate XLS files in

Reports/

.processed-files.log

Reports/schedule-e-draft.csv

One section per property. Columns:

Property

Line

Category

Amount

Details

Schedule E line reference:

Reports/business-trips.csv

Columns:

Business

Trip Name

Destination

Dates

Category

Vendor

Amount

Per Diem Equivalent

Recommended Method

Notes

Include a summary row per trip with:

• Total actual expenses
• Total per diem allowance
• Recommended method (Actual or Per Diem)
• Savings from recommended method

Reports/donations-summary.csv

Columns:

Date

Organization

Amount

Cash/Non-Cash

501c3 Confirmed

Description

Source File

Reports/w2-summary.csv

Columns:

Employer

EIN

Wages (Box 1)

Federal Withheld (Box 2)

SS Wages (Box 3)

SS Withheld (Box 4)

Medicare Wages (Box 5)

Medicare Withheld (Box 6)

State

State Wages

State Withheld

Source File

Reports/1099-summary.csv

Columns:

Type

Payer

TIN (last 4)

Amount

Box

Description

Source File

Step 9: Completion Summary

Present a clear summary to the user:

=== Tax Organizer — Complete ===

FILES
  Processed (new):      12
  Skipped (existing):    5
  Duplicates found:      2
  Needs manual review:   1 (see Unclassified/)

INCOME & EXPENSES BY PROPERTY
  123 Main St (Residential Rental)
    Rents received:     $ 24,000.00
    Total expenses:     $ 15,432.18
    Depreciation:       $  8,181.82
    Net income (loss):  $    386.00

  456 Oak Ave (Commercial Rental)
    Rents received:     $ 36,000.00
    Total expenses:     $ 12,100.00
    Depreciation:       $  5,128.21
    Net income (loss):  $ 18,771.79

BUSINESS TRIPS
  Property Inspection — Austin, TX (Mar 10–12)
    Actual expenses:    $    842.00
    Per diem allowance: $    716.00
    Recommendation:     Use ACTUAL method (saves $126.00)

  BiggerPockets Conf — Las Vegas, NV (Sep 5–8)
    Actual expenses:    $  1,450.00
    Per diem allowance: $  1,680.00
    Recommendation:     Use PER DIEM method (saves $230.00)

DONATIONS
  Total charitable contributions: $2,500.00
  Cash: $2,000.00 | Non-cash: $500.00

W-2 SUMMARY
  Total wages:          $ 85,000.00
  Total federal withheld: $ 15,300.00

1099 SUMMARY
  1099-NEC:  $12,000.00 (2 forms)
  1099-INT:  $   450.00 (1 form)

REPORTS GENERATED
  Reports/schedule-e-draft.csv
  Reports/business-trips.csv
  Reports/donations-summary.csv
  Reports/w2-summary.csv
  Reports/1099-summary.csv

NEXT STEPS
  1. Review Unclassified/ for 1 file needing manual classification
  2. Verify Schedule E draft against actual IRS Form 1040 Schedule E
  3. Provide reports to your tax preparer
  4. Drop additional documents anytime and re-run to update

Sample Content Reference

These are the annotated example templates the skill uses to explain folder structure and README format to the user (e.g., when the user asks "what should my business README look like?"). Do not create a

_sample/

Root folder README example

# Tax Documents — 2025

## Instructions

This folder organizes your tax documents for the 2025 tax year.

### How to use

1. **Drop receipts and documents** into the tax year folder
   — or into any existing business subfolder
2. **Run the skill** — it scans your documents, identifies business
   lines, and guides you through setup
3. **Add more documents anytime** — the skill detects new files and
   only processes what's changed

### Special folders

- `W2s/` — Drop W-2 forms here (organized for reference)
- `1099s/` — Drop all 1099 forms here
- `Donations/` — Drop charitable contribution receipts here

## Filing Information

- **Tax Year**: 2025
- **Filing Status**: Married Filing Jointly
- **Preparer**: Jane Smith

Business folder README example

# 789 Example Boulevard Rental

## Business Information

- **Type**: Residential Rental
  <!-- Options: Residential Rental, Commercial Rental, Royalties,
       Partnership (K-1), S-Corp (K-1), Freelance/Self-Employment,
       Farm Rental -->
- **EIN**: 98-7654321
  <!-- Your Employer Identification Number, if you have one -->
- **Address**: 789 Example Blvd, Denver, CO 80202
- **Ownership**: 100%
  <!-- Your ownership percentage. Use 50% for 50/50 partnerships, etc. -->

## Property Details

<!-- Only include this section for rental properties -->

- **In-Service Date**: 2020-03-01
  <!-- The date you started renting the property -->
- **Cost Basis**: $350,000
  <!-- Total purchase price including closing costs -->
- **Land Value**: $75,000
  <!-- Assessed land value (check your property tax statement) -->
- **Depreciation Method**: Straight-line (27.5 years residential)
  <!-- Residential: 27.5 years | Commercial: 39 years -->

## Business Trips

<!-- List any trips related to this property.
     The skill will automatically match receipts that fall within
     these date ranges to this trip. -->

### Property Visit — Denver, CO

- **Dates**: April 5–7, 2024
- **Purpose**: Tenant move-out inspection and unit turnover

## Important Events

<!-- Note anything that affects how expenses are categorized -->

- **2024-04-10**: Full interior repaint — maintenance ($3,200)
- **2024-08-15**: New roof — capital improvement ($12,000)
  <!-- Capital improvements are depreciated separately, not expensed -->

## Notes

Property managed by Denver Property Mgmt Co.
Monthly management fee: $175 (2% of rent).

Edge Cases

• Multi-page PDF: Treat as a single document. Extract data from all pages.
• Image quality: If an image/scan is too low quality to read, flag it for manual review rather than guessing.
• Multiple amounts: Some invoices have multiple line items. Extract the total and note individual items in the description.
• Foreign currency: Flag for manual review. Note the currency and suggest the user provide the USD equivalent.
• Personal vs. business: If a receipt could be personal or business (e.g., Home Depot), classify based on context ( property address, trip dates) or ask the user.
• Partial year ownership: Use mid-month convention for depreciation. Prorate rental income if property was not rented the full year.
• Multiple properties on one receipt: If a vendor receipt covers multiple properties, ask the user how to split the expense.
• Duplicate file names: The hash-based system handles this — same content with different names is flagged as a duplicate.
• Empty or corrupted files: Flag for manual review. Do not process.
• Spreadsheets (XLS/XLSX): Use the

  /xlsx

  skill to read and process Excel files. These might be bank statements, accounting exports, or property management reports with multiple transactions. CSV files can be read directly.

Security Notes

• Never store full SSNs or TINs — only reference last 4 digits in reports
• Do not transmit tax documents outside the local filesystem
• Preserve originals — always copy, never move or delete source files
• All processing is local — no external API calls except GSA per diem rate lookup

Cryptocurrency & Mining Income (Schedule C)

Spreadsheet Pool Exports

Mining pools typically export daily payout data as

.xlsx

/xlsx

• Time of Settlement

  — income date (use date portion only; UTC offset doesn't change the tax date)

• Amount (Total)

  — BTC received that day (this is the income, at FMV on that date)

• Avg. Hashrate Per Day

  — informational; document for activity records

• Description

  — payment scheme (FPPS, PPLNS, etc.)

USD FMV Conversion

Each day's BTC payout is ordinary income at the fair market value on the date received (IRS Rev. Rul. 2023-14). To calculate USD income:

1. Fetch daily BTC closing prices from Yahoo Finance:

   https://query1.finance.yahoo.com/v8/finance/chart/BTC-USD?interval=1d&period1=UNIX_TS&period2=UNIX_TS
   

   • Replace

     UNIX_TS

     with Unix timestamps for your date range
   • CoinGecko free API returns 401 — prefer Yahoo Finance
2. Match each settlement date to the closing price for that date

3. USD income = BTC amount × closing price

4. Sum for total Schedule C mining income

Generate a

Reports/btc-mining-income.csv

Cost Basis of Unsold BTC

The FMV at time of receipt becomes the cost basis for any BTC held and later sold (reported on Schedule D / Form 8949 in the year of sale). The per-day breakdown in

btc-mining-income.csv

Business Closure Mid-Year

If the business closed partway through the year, confirm the export covers the full active period. A partial-year export can be complete if the business stopped operating before year-end — do not flag it as missing data once the user confirms the closure date.

Additional Reports for Crypto Businesses

Generate these extra reports alongside the standard set:

• Reports/schedule-c-draft.csv

  — Income, expenses, net profit/loss for each Schedule C business

• Reports/btc-mining-income.csv

  — Daily breakdown: date, BTC, USD price, USD income

• Reports/bitcoin-mining-detail.csv

  — Summary metadata (total BTC, total USD, price source, action items)

International Business Travel

Per Diem Rate Source

For domestic US travel, use GSA per diem rates (gsa.gov). For international travel, use US State Department / DoD per diem rates — not GSA.

• Lookup URL:

  https://www.perdiem101.com/oconus/{YEAR}/{CITY-COUNTRY-rate}

  (reliable mirror)
• Official source:

  allowances.state.gov

  (may be slow or return errors for some country codes)
• Rates include: lodging (per night) and M&IE (meals and incidental expenses, per day)
• Rates are typically published per city and updated periodically (check effective date)

First/Last Day Rule (International)

Same as domestic: 75% of M&IE on the first and last calendar day in the foreign country.

First day in foreign country:   M&IE × 75%
Full days in foreign country:   M&IE × 100% each
Last day in foreign country:    M&IE × 75%

Do not count the US departure or return days as foreign-country days unless the taxpayer overnights abroad on that day.

Stayed with Family / Friends — $0 Lodging

When the taxpayer stayed with family or friends instead of a hotel:

• Lodging deduction = $0 (no actual expense)
• M&IE per diem still applies for meals — use per diem method when no meal receipts exist
• The per diem lodging rate is irrelevant (not deductible without actual cost)
• Note this clearly in

  business-trips.csv

  so the accountant is not confused by the $0

Missing Receipts — Per Diem vs. Actual

If meal receipts are unavailable, recommend the per diem method for M&IE. Transportation and airfare always use actual cost (per diem does not cover these). Document the choice in the report — IRS requires consistency within a single trip.

Combined Property Tax Payments

Multiple Parcels on One Payment

County tax portals often allow paying multiple parcels in a single transaction. When the same payment confirmation covers more than one property (e.g., a primary residence and a rental), the document shows parcel numbers and amounts but not property addresses.

Do not guess which parcel belongs to which property from the payment PDF alone.

Steps to resolve:

1. Ask the user to upload the official county tax bills (not the payment confirmation) — these always show the situs (property) address alongside the parcel number.
2. Alternatively, look up each parcel on the county assessor's website.
3. Once confirmed, document the mapping in each property's

   README.md

   .

Near-Duplicate Payment Confirmations

The same payment event can produce two different PDF files with different SHA-256 hashes:

• One saved from the payment portal immediately after submitting
• One printed later from the payment history page

These are not true duplicates (different hashes) but represent the same deduction. Flag as near-duplicate, keep the cleaner copy in the property folder, and move the other to

Unclassified/

Parcel → Property Assignment Tip

When unsure, compare the assessed value / tax amount to the property values:

• Higher-value property → typically higher annual tax bill
• Lower-value property → typically lower annual tax bill

Use this as a sanity check, but always confirm with actual tax bills before finalizing reports.

Additional Edge Cases (Discovered in Practice)

Property Tax: Installment Timing

Many counties collect property tax in two installments that may cross tax years:

• Installment 1 (due ~November): often paid in September of the same tax year
• Installment 2 (due ~April): paid in the following calendar year

Both installments paid in the same calendar year are deductible in that year for cash-basis taxpayers. Always check payment dates, not due dates.

Personal vs. Business Software Licenses

Some software vendors sell "Personal" and "Business" tiers. A "Personal" license used exclusively for business is still deductible — the license type doesn't determine deductibility; actual use does. Ask the user to confirm usage percentage and note it in the report.

Mortgage Interest Deduction Limit (Primary Residence)

For MFJ filers, mortgage interest is deductible only on the first $750,000 of principal. If the outstanding balance exceeds $750,000, prorate the deductible interest:

Deductible Interest = Total Interest × ($750,000 / Average Outstanding Balance)

Flag this in the Schedule A notes and provide the calculation to the preparer.

Form 1095-A (Health Insurance Marketplace)

The 1095-A is not a 1099 but should be classified alongside income forms in

1099s/

• Monthly enrollment premium (Box A)
• Monthly SLCSP premium (Box B) — used to calculate allowed credit on Form 8962
• Advance Premium Tax Credit received (Box C) — must be reconciled on Form 8962

Always flag that Form 8962 is required when a 1095-A is present. If APTC was received for only part of the year (e.g., Jan–Oct), note the reason and confirm with the user.

Investment Interest Expense (Margin Interest)

Margin interest paid to a broker is reported on the year-end statement (not a 1099). It is potentially deductible on Schedule A, Form 4952, up to net investment income. When present, include it in the 1099 summary with a note about deductibility and Form 4952.

Corrected 1099s

A corrected 1099 (marked "CORRECTED" on the form) supersedes the original. When both exist:

• Use the corrected version for all report amounts
• Keep both files organized (rename with "CORRECTED" in the filename)
• Note the correction in the 1099 summary

Taiwan / Foreign E-Invoices

Taiwan uses a government e-invoice system (電子發票 / GUI). These PDFs look like foreign-language receipts with a QR code and a random 4-digit verification code. Extract: vendor name, date (in ROC calendar format — add 1911 to convert to AD year), amount in New Taiwan Dollars (NT$), and convert to USD using the exchange rate on that date.

Technical Notes

File Hashing with Special Characters

Use Python

hashlib

sha256sum

xargs

• Parentheses, ampersands, accented characters, CJK characters, or long spaces
• Shell

  xargs sha256sum

  silently produces the empty-file hash for unescaped names

import hashlib, os
h = hashlib.sha256()
with open(path, 'rb') as f:
    h.update(f.read())
digest = h.hexdigest()

Python Dependencies

pandas

openpyxl

.xlsx

pip install pandas openpyxl --quiet

Working Directory

Always confirm the working directory before running file scans. The

.processed-files.log

os.walk('.')

BTC Price API — Yahoo Finance

GET https://query1.finance.yahoo.com/v8/finance/chart/BTC-USD
    ?interval=1d
    &period1={unix_timestamp_start}
    &period2={unix_timestamp_end}

Returns OHLCV data. Use the

close