/tax-guide

name: tax-guide
description: "Run a guided tax-preparation questionnaire and create a document checklist and preparation plan."

/tax-guide — Personalized Tax Prep Guide

A guided Q&A that assesses your tax situation and generates a personalized preparation plan. Outputs a recommendation (self-file, self-file with care, or hire a professional), a document checklist, a suggested workflow, and privacy guidance.

---

Phased Execution

Phase 0: Pre-checks

Before starting the Q&A, verify the environment:

1. Confirm Claude Code is running (you're reading this, so it is) 2. Check if a prior `/tax-guide` output exists in the working directory — if so, note it and offer to update rather than re-run 3. Set the tax year to the most recent completed calendar year (e.g., if today is in 2026, the tax year is 2025)

---

Phase 1: Collect — The Q&A

Ask each question one at a time. Wait for the user's response before proceeding. Keep the tone conversational and concise.

**Question 1: Primary income** > What's your primary income source? > - (a) W-2 salary only — one employer > - (b) W-2 salary + side income (consulting, freelance, gig work) > - (c) Fully self-employed / independent contractor > - (d) Multiple income types (salary + rental + investment + other)

Store as `income_type`.

**Question 2: 1099 forms** > How many 1099 forms do you expect to receive this year? (1099-NEC, 1099-MISC, 1099-K, etc.) > - (a) None > - (b) 1-2 > - (c) 3 or more

Store as `num_1099s`.

**Question 3: Itemized deductions** > Do you itemize deductions (or are you unsure)? > - (a) Yes, I itemize > - (b) No, I take the standard deduction > - (c) Not sure

If answer is (c), provide a one-sentence explanation: "You itemize if your mortgage interest + state/local taxes + charitable giving + medical expenses exceed the standard deduction. The standard deduction changes annually — check IRS.gov for the current year's amounts. Most homeowners with a mortgage itemize."

Store as `itemize_status`.

**Question 4: Complexity flags** > Do any of these apply to you? (Select all that apply, or "none") > - Foreign income (work, consulting, or investments abroad) > - Rental property > - K-1 from a partnership, S-corp, or trust > - Stock options (ISOs, NSOs) or significant RSU vests > - Cryptocurrency beyond simple buy/sell > - None of the above

Store as `complexity_flags[]`.

**Question 5: Prior filing method** > How did you file last year? > - (a) Tax software myself (TurboTax, FreeTaxUSA, H&R Block, etc.) > - (b) CPA or tax preparer > - (c) This is my first year filing (or first complex return)

Store as `prior_method`.

**Question 6: AI comfort level** > How comfortable are you with Claude Code? > - (a) New to it — just installed or exploring > - (b) Have it set up, used it for a few things > - (c) Power user — I build skills and use MCP integrations

Store as `ai_comfort`.

**Question 7: Gmail MCP** > Do you have Gmail MCP configured in Claude Code? > - (a) Yes > - (b) No > - (c) What's that?

If answer is (c), briefly explain: "Gmail MCP lets Claude Code search and read your email. The tax document collection skill uses it to find W-2s, 1099s, and other tax documents in your inbox automatically. It's optional — you can still use the workflow without it, you'll just collect documents manually."

Store as `gmail_mcp`.

**Question 8: Goal** > What's your main goal right now? > - (a) Organize my tax documents before I start filing > - (b) File my own taxes start to finish > - (c) Prepare organized materials for my CPA > - (d) Just exploring — want to understand what's possible

Store as `goal`.

---

Phase 2: Process — Routing Logic

Apply these rules to generate the recommendation:

**Recommendation: Hire a professional**

• ANY complexity flag is checked (foreign income, rental property, K-1, stock options, crypto), OR
• `income_type` is (d) multiple types AND `num_1099s` is (c) 3+

**Recommendation: Self-file with care**

• `income_type` is (b) W-2 + side income, OR
• `num_1099s` is (b) 1-2, OR
• `itemize_status` is (a) yes AND `prior_method` is (c) first time

**Recommendation: Self-file**

• `income_type` is (a) W-2 only, AND
• `num_1099s` is (a) none, AND
• No complexity flags

(If rules conflict, use the higher-risk recommendation.)

**Document checklist mapping:**

| If the user has... | Collect these | |---|---| | W-2 salary | W-2 from employer(s) | | Side consulting / 1099-NEC | 1099-NEC from each client, business expense receipts | | Investments | 1099-DIV, 1099-B, 1099-INT from each institution | | RSU vests | 1099-B + supplemental stock plan statement | | Foreign income (complexity flag) | Foreign income documents, foreign tax statements, Form 2555/1116 info for CPA | | Rental property (complexity flag) | Rent received records, all property expenses, insurance, prior-year depreciation schedule | | K-1 (complexity flag) | Schedule K-1 from partnership/S-corp/trust (often arrives late — March or April) | | Stock options (complexity flag) | Exercise statements, Form 3921 (ISO) or Form 3922 (ESPP), cost basis records | | Mortgage (itemizer) | 1098 from lender | | Charitable giving (itemizer) | Donation receipts, tracking spreadsheet | | Medical expenses (itemizer) | Credit card statements, insurance EOBs, pharmacy receipts | | Childcare | Provider receipts, FSA statements | | Student loans | 1098-E | | Property tax (itemizer) | Tax bill from county assessor | | CPA or professional filing | Prior-year tax return (CPA needs it for carryforwards, depreciation, history) |

Include rows that match the user's answers: income type, complexity flags, itemize status, and goal.

**Workflow mapping:**

| Situation | Relevant skills & pages | |---|---| | Any filing | [Privacy & Setup](https://claudeblattman.com/tax-workflow/before-you-start/privacy-and-setup/) | | Gmail MCP available | `/tax-collect` skill for automated document collection | | No Gmail MCP | Manual document collection using the checklist | | Sched