tax-advisor

name

tax-advisor

description

After filing, analyzes the completed return and recommends actions to reduce tax liability for the next year. Runs what-if scenarios showing the dollar impact of each recommendation on federal, Maryland state, and local taxes. Triggers on: 'what should I do differently next year', 'how to reduce my taxes', 'tax planning', 'what if I maxed my 401k', 'tax optimization', 'next year tax strategy', 'reduce my tax bill', 'tax savings opportunities', 'should I change my withholding', 'how much would I save'.

tax-advisor

Post-filing tax planning — analyzes this year's completed return and models what-if scenarios to quantify the dollar impact of tax-saving strategies. This is the last skill in the workflow, run after filing to plan for next year. Uses data from analysis/tax-doc-summary.csv and the user's filed return values to feed what_if.py.

Session Handoff

Every conversation starts here:

1. Check if analysis/tax-doc-summary.csv exists
2. If it exists:
   • Count distinct documents and total rows
   • Report: "I have your extracted tax data (N documents, M values). Ready to run tax planning scenarios."
3. If it does NOT exist:
   • Tell the user: "No extracted tax data found. Run /tax-prep first to extract your document values, then file your return with /tax-cheatsheet and /tax-audit, and come back here for planning."
   • Stop — do not proceed without the CSV
4. If the user has already run /tax-audit, offer to reuse those filed return values as the baseline
5. Otherwise, collect the baseline data from the user:
   • Filing status
   • Wages (primary and spouse, both W-2 Box 1 and Box 5 Medicare wages)
   • Interest, dividends (ordinary and qualified), capital gains
   • Schedule C net profit/loss
   • Deduction components (mortgage interest, state/local tax, real estate tax, charitable)
   • Retirement contributions already made (401k, IRA, HSA)
   • County of residence
   • US obligation interest (for MD subtractions)
   • QBI carryforward from current year (if any)
6. Ask which scenarios to explore, or offer to run all scenarios

Scenario Table

#	Scenario	What It Models	Script Parameter	Timing	Reference File(s)
1	Max 401(k) primary	Primary spouse contributes $23,500 pre-tax	max_401k	Plan for next year	retirement-hsa-limits.md
2	Max 401(k) spouse	Spouse contributes $23,500 pre-tax	max_401k_spouse	Plan for next year	retirement-hsa-limits.md
3	Max 401(k) both	Both spouses max out 401(k)	max_401k_both	Plan for next year	retirement-hsa-limits.md
4	Traditional IRA	$7,000 IRA contribution (checks deductibility)	add_ira	Before deadline (Apr 15)	retirement-hsa-limits.md
5	Traditional IRA spouse	Spouse $7,000 IRA contribution	add_ira_spouse	Before deadline (Apr 15)	retirement-hsa-limits.md
6	Max HSA (family)	$8,550 family HSA contribution	max_hsa	Before deadline (Apr 15)	retirement-hsa-limits.md
7	Increase charitable	$10,000 charitable contributions	increase_charitable	Plan for next year	2025-tax-numbers.md
8	Donor-advised fund	Large one-time $25,000 DAF contribution	charitable_daf	Plan for next year	2025-tax-numbers.md
9	Adjust withholding	Target $0 refund/balance due	adjust_withholding	Plan for next year	2025-tax-numbers.md
10	Increase Schedule C revenue	Model business becoming profitable	increase_schedule_c_revenue	Plan for next year	schedule-c-guide.md, self-employment-qbi.md
11	Add Schedule C expenses	Additional business deductions	add_schedule_c_expenses	Plan for next year	schedule-c-guide.md

Advisor Workflow

Step 1 — Build Baseline

Reconstruct the baseline from the user's filed return. Use form_line_lookup.py from /tax-cheatsheet to pull values from the CSV where possible:

python .claude/skills/tax-cheatsheet/scripts/form_line_lookup.py '{"csv_path": "analysis/tax-doc-summary.csv", "document_filter": "W-2", "box_filter": "Box 1", "operation": "sum"}'

Build the baseline JSON dict with all fields from the Input Schema Reference below. Key extraction mappings:

Baseline Field	CSV Source	Script Query
wages_primary	W-2 Box 1 (primary)	document_filter: "W-2 (primary name)", box_filter: "Box 1"
wages_spouse	W-2 Box 1 (spouse)	Same with spouse name
medicare_wages_primary	W-2 Box 5 (primary)	box_filter: "Box 5"
medicare_wages_spouse	W-2 Box 5 (spouse)	Same with spouse name
interest	1099-INT Box 1	document_filter: "1099-INT", box_filter: "Box 1", operation: "sum"
dividends_ordinary	1099-DIV Box 1a	document_filter: "1099-DIV", box_filter: "Box 1a", operation: "sum"
capital_gain	User's filed 1040 Line 7	Ask user (Schedule D result)
schedule_c_net	User's filed Schedule C Line 31	Ask user
mortgage_interest	1098 Box 1	document_filter: "1098", box_filter: "Box 1", operation: "sum"
state_local_tax	W-2 Box 17 (all)	document_filter: "W-2", box_filter: "Box 17", operation: "sum"
real_estate_tax	1098 Box 4	document_filter: "1098", box_filter: "Box 4"

Step 2 — Run Scenarios

For each scenario the user wants to explore, invoke what_if.py:

python .claude/skills/tax-advisor/scripts/what_if.py '{"baseline": {...}, "scenario": {"name": "max_401k_both", "retirement_contributions_primary": "23500", "retirement_contributions_spouse": "23500"}}'

Parse the JSON output. Each result contains baseline, modified, savings, and notes.

Step 3 — Prioritize Results

Sort all scenario results by savings.total_tax (descending — largest savings first). Group into:

1. Actionable before filing deadline — IRA contributions, HSA contributions (can still be made for prior tax year before April 15)
2. Plan for next year — 401(k) enrollment, charitable strategy, withholding adjustment, business optimization

Step 4 — Present Results

Use the Output Template below. For each scenario:

1. Explain what it is and who it applies to, citing the relevant curated reference file
2. Show the dollar impact from the script output
3. Note any phase-outs or limitations at the user's income level (from the notes array)
4. Clearly mark timing: "Still do before April 15" vs "Plan for next year"

Step 5 — Combined Analysis

If the user wants to see the combined impact of multiple strategies, run a single combined scenario through what_if.py (not a sum of individual savings — tax is nonlinear):

python .claude/skills/tax-advisor/scripts/what_if.py '{"baseline": {...}, "scenario": {"name": "custom", "retirement_contributions_primary": "23500", "retirement_contributions_spouse": "23500", "hsa_contributions": "8550", "charitable": "10000"}}'

Input Schema Reference

baseline

Collect these values from the user's filed return and extracted CSV:

Key	Source	Description
filing_status	User input	MFJ, Single, MFS, or HoH
wages_primary	W-2 Box 1 (primary)	W-2 wages after any existing 401(k)
wages_spouse	W-2 Box 1 (spouse)	Spouse W-2 wages
medicare_wages_primary	W-2 Box 5 (primary)	Medicare wages (before 401(k) reduction)
medicare_wages_spouse	W-2 Box 5 (spouse)	Spouse Medicare wages
interest	1099-INT Box 1 sum	Total taxable interest
dividends_ordinary	1099-DIV Box 1a sum	Total ordinary dividends
dividends_qualified	1099-DIV Box 1b sum	Qualified dividends (for reference)
capital_gain	1040 Line 7	Net capital gain or loss
schedule_c_net	Schedule C Line 31	Net business profit or loss
other_income	1040 Line 8	Other income (Schedule 1)
adjustments	Other adjustments	Other Schedule 1 adjustments
retirement_contributions_primary	Current 401(k)	Primary current 401(k) contribution
retirement_contributions_spouse	Current 401(k)	Spouse current 401(k) contribution
hsa_contributions	Current HSA	Current HSA contribution
mortgage_interest	1098 Box 1	Mortgage interest paid
state_local_tax	W-2 Box 17 sum	State/local income tax paid
real_estate_tax	1098 Box 4	Property tax paid
charitable	Schedule A Line 12	Charitable contributions
medical_expenses	Schedule A Line 1	Gross medical expenses
other_itemized	Schedule A other	Other itemized deductions
county	User input	Maryland county (e.g., "Montgomery")
us_obligation_interest	1099-INT Box 8	U.S. obligation interest (MD subtraction)
qbi_carryforward	Form 8995 Line 16	QBI loss carryforward from current year
num_exemptions	User input	Number of MD exemptions (default: 2 MFJ)

scenario

Key	Description
name	Scenario identifier (see Scenario Table)
Additional fields	Override values specific to the scenario

Output Template

Present the planning results in this format:

## Tax Planning Report

Based on your 2025 filed return (filing status: [status], AGI: $[amount]).

### Still Do Before April 15

| # | Strategy | Federal Savings | State Savings | Total Savings | Note |
|---|----------|-----------------|---------------|---------------|------|
| 1 | [Strategy name] | $X | $Y | $Z | [Key note] |

*If any before-deadline strategies show $0 savings, explain why (e.g., "IRA not deductible at your income level").*

### Plan for Next Year

| # | Strategy | Current → Proposed | Federal Savings | State + Local Savings | Total Savings |
|---|----------|-------------------|-----------------|----------------------|---------------|
| 1 | Max 401(k) both | $0 → $47,000 | $X | $Y | $Z |
| ... | ... | ... | ... | ... | ... |

*Ranked by total savings (largest first).*

### Scenario Details

For each scenario:

#### [Scenario Name]

**What:** [One-line explanation]
**Who it applies to:** [Eligibility check at user's income level]
**Impact:**
- Current total tax: $X
- Modified total tax: $Y
- **Annual savings: $Z** (effective rate: X% → Y%)
**Notes:**
- [Phase-out or limitation notes from script output]
- *(Source: [reference-file.md], [section])*

### Combined Impact

If you implemented [list of recommended strategies]:
- Current total tax: $X
- Projected total tax: $Y
- **Total annual savings: $Z**
- Effective rate: X% → Y%

*Note: Combined savings account for interaction effects — they differ from summing individual scenarios.*

---
*Disclaimer: This analysis assists with tax planning. It does not constitute tax advice. Retirement contribution limits, IRA deductibility phase-outs, and HSA limits should be verified against IRS.gov (see retirement-hsa-limits.md). Consult a qualified tax professional for your specific situation.*

Important output rules:

• Always show both federal AND state/local impact — state savings are significant at MD rates
• When a scenario shows $0 savings, explain why (phase-out, not eligible, etc.)
• When retirement/HSA limits are used, include the verification warning from the script's notes array
• Round dollar amounts to whole dollars in the summary table; cents in detail sections
• The combined scenario must be run as a single what_if.py invocation, not summed

Mandatory Rules

1. Never attempt to reconstruct redacted SSNs or other PII
2. All calculations run through what_if.py — never do arithmetic in natural language
3. Every tax rule must cite a file in reference/curated/ — format: (Source: filename.md, section)
4. If a rule cannot be verified from curated references: "I cannot verify this from provided IRS materials — check IRS.gov"
5. Any saved forms must leave SSN, bank routing, account number, and signature fields blank
6. No personal information stored in skill files
7. Retirement and HSA limits ($23,500 for 401k, $7,000 for IRA, $8,550 for HSA) are sourced from retirement-hsa-limits.md. Every mention must include: "verify against IRS.gov" (Source: retirement-hsa-limits.md, Verification note)

Script Reference

Script	Purpose	Location
what_if.py	Model tax scenarios, compute dollar savings for federal + MD state + local	.claude/skills/tax-advisor/scripts/

Also available from other skills (do not modify):

Script	Purpose	Location
form_line_lookup.py	Query CSV by document type and box	.claude/skills/tax-cheatsheet/scripts/
standard_vs_itemized.py	Compare standard vs itemized deduction	.claude/skills/tax-cheatsheet/scripts/
salt_cap_calculator.py	SALT cap with MAGI phase-out	.claude/skills/tax-cheatsheet/scripts/
cross_check.py	Federal vs state consistency, tax bracket verification	.claude/skills/tax-audit/scripts/

Related Skills

• /tax-prep — Extract document values into CSV (run first)
• /tax-cheatsheet — Line-by-line form filling help (run second)
• /tax-audit — Cross-check before filing (run third, before this skill)