flow-build-estimate

flow-build-estimate

Trigger: Called by op-quarterly-estimate Produces: Estimated tax calculation at vault/tax/00_current/YYYY-QN-estimate.md

What It Does

Reads YTD income and withholding data from across the tax vault and produces a current-quarter estimated tax calculation using both IRS-recognized methods, returning whichever produces the lower required payment to avoid underpayment penalties.

Income aggregation. The flow calls task-extract-income-ytd to get a structured breakdown of all YTD income: W-2 wages (gross, year-to-date, from pay stubs in vault/tax/00_current/), self-employment / 1099-NEC income (from freelance/consulting records), rental income net of deductible expenses (from estate or business records), short-term capital gains (from brokerage records — held ≤1 year, taxed as ordinary income), long-term capital gains (held >1 year, taxed at preferential rates of 0%/15%/20%), qualified dividends (taxed at long-term capital gains rates), ordinary dividends (taxed as ordinary income), and other income.

Withholding and prior payments. YTD federal withholding from W-2 pay stubs. Any prior quarterly estimated payments already made this year (from vault/tax/00_current/). Both are subtracted from the required payment before arriving at the amount due.

Method A: Safe Harbor. Calls flow-safe-harbor-calc to compute the quarterly safe-harbor target (100% of prior-year tax ÷ 4, or 110% if prior-year AGI >$150k). Subtracts YTD withholding and prior quarterly payments already made to get the remaining balance due. See flow-safe-harbor-calc for full math.

Method B: Current Year Actual. Annualize YTD income by multiplying by (12 ÷ months completed). Apply standard deduction or estimated itemized deductions from config. Calculate estimated federal income tax using current year tax brackets. For self-employment income, add 15.3% SE tax (12.4% Social Security on first $176,100, 2.9% Medicare — no cap) and subtract half the SE tax as a deduction. Subtract qualified business income deduction (QBI, up to 20% of qualified business income) if applicable. The result is the estimated annual tax liability; divide by 4 and subtract withholding and prior payments.

Recommended payment. Return the lower of Method A and Method B as the recommended quarterly payment. Show both calculations side by side for transparency. Include a note: "Penalty risk if no payment is made: approximately [calculated penalty using IRS underpayment rate × remaining balance]."

Triggers

• "estimated tax"
• "quarterly payment due"
• "what do I owe this quarter"
• "calculate estimated tax"
• "Q1/Q2/Q3/Q4 estimate"
• "how much should I pay in estimated tax"
• "safe harbor calculation"
• "avoid underpayment penalty"

Steps

1. Call task-extract-income-ytd to get structured YTD income by source type
2. Read YTD withholding total from pay stub records in vault/tax/00_current/
3. Read prior quarterly estimated payments already made this year from vault/tax/00_current/
4. Calculate Method A (Safe Harbor) by calling flow-safe-harbor-calc; subtract withholding and prior payments to get net quarterly amount
5. Annualize YTD income (total × 12 ÷ months elapsed)
6. Apply estimated deductions (standard deduction or configured itemized estimate) to annualized income
7. Calculate Method B (Actual): estimate full-year federal income tax + SE tax if applicable − QBI deduction if applicable; divide by 4, subtract withholding and prior payments
8. Compare both methods; select the lower as the recommended payment
9. Calculate underpayment penalty risk if no payment is made (IRS rate × underpayment amount × days/365)
10. Write complete calculation to vault/tax/00_current/YYYY-QN-estimate.md with both methods shown

Input

• vault/tax/00_current/ — W-2 pay stubs and 1099 documents for YTD income
• vault/tax/00_current/ — prior quarterly payments this year
• vault/tax/01_prior/ — prior period records for trend comparison
• vault/tax/config.md — prior year tax liability, filing status, deduction method, SE income flag, QBI eligibility
• Income records from vault/wealth/ or vault/business/ if cross-plugin sharing is configured

Output Format

Markdown document at vault/tax/00_current/YYYY-QN-estimate.md:

• Header: quarter, due date, run date
• YTD Income table: Source | YTD Amount | Notes
• YTD Withholding: total federal withheld + prior quarterly payments
• Method A (Safe Harbor): prior year liability, multiplier, quarterly amount, net due
• Method B (Actual): annualized income, estimated deductions, estimated tax, quarterly amount, net due
• Recommended Payment: [lower of A/B] — due by [date] via [IRS Direct Pay or EFTPS]
• Underpayment penalty estimate if no payment made

Configuration

Required in vault/tax/config.md:

• prior_year_tax_liability — total federal tax from last year's return (Form 1040, line 24)
• prior_year_agi — AGI from last year's return (to determine 110% multiplier)
• filing_status — for tax bracket application
• deduction_method — standard | itemized (estimated itemized amount if itemizing)
• se_income — true | false (triggers SE tax calculation)
• qbi_eligible — true | false (triggers 20% QBI deduction)

Error Handling

• If prior year tax liability is not in config: prompt "Prior year tax liability is required for the safe harbor calculation. Find it on your prior year Form 1040, line 24, and add it to vault/tax/config.md."
• If YTD income records are sparse (less than 2 months of data): note that the annualization may be inaccurate; recommend using Method A (safe harbor) for more reliability
• If the recommended payment is $0 or negative (withholding exceeds liability): report "Withholding appears sufficient — no estimated payment required this quarter" and explain why

Vault Paths

• Reads from: ~/Documents/aireadylife/vault/tax/01_prior/ — prior period records
• Reads from: ~/Documents/aireadylife/vault/tax/00_current/ (income records)
• Reads from: ~/Documents/aireadylife/vault/tax/00_current/ (prior payments)
• Reads from: ~/Documents/aireadylife/vault/tax/config.md
• Writes to: ~/Documents/aireadylife/vault/tax/00_current/YYYY-QN-estimate.md