| name | china-tax |
| description | This skill should be used when the user asks about China tax-resident individual overseas brokerage evidence workflows, especially IBKR Flex dividends, Form 1042-S reconciliation, U.S. withholding tax, foreign tax credit, RMB FX evidence, 美股分红预扣税, 境外所得抵免, IBKR 年度报税工具, 1042-S 怎么用于中国个税, 境外股票收益报税, and neutral year-end evidence readiness for China tax filing. Use it as an official-source workflow reference and informational estimate guide, not final filing advice.
|
| version | 2.2.0 |
China Tax Reference and Planning for Overseas Brokerage Data
Prepare official-source evidence reviews, informational annual China individual income tax estimates, and year-end planning reviews for China tax residents using IBKR/Flex data first. Focus on overseas income management, foreign tax credit, treaty withholding sanity checks, RMB conversion assumptions, filing evidence, and tax-planning review items.
Safety Boundary
- Provide informational estimates, evidence organization, and planning checklists only; never state a final tax payable amount or filing position as definitive.
- Recommend confirmation with a qualified tax professional or competent tax authority before filing.
- Do not determine China tax residency conclusively; use only explicit user-provided residency assumptions and mark them for review.
- Recheck official sources and effective dates for the relevant tax year before relying on rules or forms.
- Treat default rates such as 20% for dividend estimates as configurable assumptions, not final law application.
- Do not invent missing 1042-S amounts, brokerage gross income, withholding tax, country allocation, income category, cost basis, realized gains, or RMB exchange rates.
- Keep U.S. treaty withholding checks separate from China IIT calculation.
- Mark ambiguous or unsupported tax treatment as
review_required.
- Do not provide tax evasion, concealment, false reporting, or illegal avoidance advice.
Reference First
Consult references/official-tax-rules-and-implementation-plan.md before answering detailed calculation, treaty, overseas-income management, CRS, foreign-tax-credit, or implementation questions. It contains official-source links, rule summaries, formulas, output tables, a web-app pattern review, and a staged implementation plan.
Current Capability
Handle these tasks as research, design, evidence preparation, and manual estimate workflows:
- Explain how Form 1042-S, brokerage data, China resident IIT, treaty withholding, and foreign tax credit fit together.
- Build evidence tables from loaded IBKR Flex cash transactions.
- Draft annual filing calculation workflows for dividends, withholding tax, opt-in STK realized-gain evidence, and later-phase 1042-S reconciliation.
- Produce year-end planning reviews that identify evidence gaps, possible withholding-rate issues, tax-lot/cost-basis issues, currency assumptions, and timing considerations.
- Produce implementation plans for deterministic code and tests.
The automated ibkr_china_tax_annual_calc MCP tool uses IBKR Flex as the primary source for Phase 1 U.S. dividend/withholding estimates and opt-in Phase 2 STK realized-gain evidence. 1042-S is optional follow-up reconciliation/evidence check, not required input. Activity-statement reconciliation beyond loaded Flex cash transactions/trades, options, derivatives, complex corporate actions, cost-basis hazards, and non-USD dividends or gains remain manual/review-required. Use scripts/china_tax_self_check.py for deterministic local-file self-check reports. Do not claim it produces final tax filing advice; it produces evidence tables, informational estimates, and review checklists.
Annual Filing Calculation Workflow
Use this workflow for annual reporting / 年度报税工具 requests. When slash commands are available, use /ibkr-trade-analyzer:china-tax-annual for annual filing evidence reviews.
- Clarify tax year, residency assumption, brokerage source, and available documents.
- Load IBKR data when available with
ibkr_fetch_data; call ibkr_china_tax_annual_calc for dividend, withholding, RMB conversion, foreign-tax-credit estimates, and opt-in STK realized-gain evidence when requested.
- Treat 1042-S as optional follow-up reconciliation/evidence check when official tax-form reconciliation is required.
- Use same-tax-year IBKR USD/RMB FX trade evidence before producing automated RMB amounts when available; otherwise require explicit documented rates. Do not present either method as an official SAFE/PBOC/state-tax exchange-rate determination.
- Compute only categories with explicit data and assumptions.
- Return evidence summary, China IIT estimate, treaty sanity check, realized-gain review items when enabled, missing inputs, and filing support checklist.
Start with U.S.-source dividends and withholding tax. Use include_realized_pnl=True only for opt-in STK realized-gain evidence/estimate workflows. Defer options, complex derivatives, corporate-action hazards, and FX gain/loss unless the user explicitly asks for planning treatment.
Year-End Tax Planning Workflow
Use this workflow for 年前税务优化建议 / year-end planning requests. When slash commands are available, use /ibkr-trade-analyzer:china-tax-year-end-plan for neutral year-end planning reviews.
- Load current portfolio, realized P&L, dividends, withholding, cash, FX, and cost-basis data when available.
- Separate compliance evidence issues from planning observations.
- Identify review items: missing 1042-S, unexpected withholding rates, missing historical statements, missing cost basis, concentrated unrealized gains/losses, and FX conversion assumptions.
- Provide neutral planning scenarios, not instructions to trade. Phrase items as “review”, “confirm”, “model”, or “ask a tax professional”.
- Avoid recommending tax-loss harvesting or transaction timing as a directive; present only calculation impacts and documentation needs.
Output Templates
Evidence Summary
| Source | Tax year | Country | Income type | Gross original | Tax withheld original | Currency | Notes |
|---|
China IIT Estimate
| Country | Category | Income RMB | China rate | China tax before credit | Foreign tax paid RMB | Creditable tax | Estimated top-up | Excess carryforward |
|---|
Treaty Withholding Sanity Check
| Country | Income type | Gross | Withheld | Actual rate | Treaty reference | Review note |
|---|
Year-End Planning Review
| Area | Evidence / metric | Review point | Possible next step |
|---|
Implementation Planning Guidance
When asked to implement commands or calculators, follow test-first development:
- Add deterministic pure functions for dividend/withholding aggregation, RMB translation, treaty sanity checks, and foreign tax credit calculation.
- Require failing fixture tests before implementation.
- Start with dividend/withholding Phase 1.
- Keep realized-gain support opt-in, STK-only, and backed by fixture tests before expanding scope.
- Preserve evidence records in output rather than only returning totals.
Additional Resources
references/official-tax-rules-and-implementation-plan.md — official-source rule summary, formulas, web-app pattern review, output tables, and staged implementation plan.scripts/china_tax_self_check.py — deterministic local-file report generator for Flex XML/CSV, 1042-S CSV, RMB FX CSV, and IBKR tax-report ZIP evidence.
