/tax-lens

description: US tax mechanics for a position or portfolio — short- vs. long-term treatment, wash-sale window check, qualified-dividend holding-period test, lot selection (specific-ID vs. FIFO), tax-loss-harvesting pairs, account placement, estimated annual tax drag — plus a --non-us module (W-8BEN, dividend withholding and treaty rates, capital-gains treatment, US estate-tax exposure, UCITS alternatives). Educational only, never tax advice

Tax Lens — What You Actually Keep

> ⚠️ **This is not tax advice.** Tax law changes, thresholds are indexed, and the right answer depends on facts this skill cannot see (filing status, state, residency, other income, treaty position). Every output of this skill must open **and** close with: *"Educational illustration of how the rules generally work — confirm with a qualified tax professional before acting."* If the user asks for a filing position, a specific dollar liability to rely on, or anything about a jurisdiction outside the US mechanics described here, say so and stop.

⚠️ Data Verification — Do This Before Any Analysis

Before running any analysis, always retrieve the latest market data for the ticker:

1. **Fetch current price** — use web search or ask the user for the live price, 52-week range, and market cap. Never assume a price from training data. 2. **Confirm key figures** — for this skill: each lot's acquisition date, cost basis, and share count; the ex-dividend dates involved; the current tax-year brackets and thresholds (long-term capital-gains brackets, the net investment income tax threshold, the annual capital-loss limit, the non-resident estate-tax exemption). Thresholds are indexed or legislated — state the tax year you are using and ask the user to confirm. 3. **State your data source** — fill in the `Data & Sources` header (next section) so the origin, as-of date, retrieval path, and confidence of every figure are explicit at the top of the output. 4. **Flag stale data explicitly** — if live data is unavailable, display this warning before proceeding:

> ⚠️ **Live data unavailable.** The following analysis uses training-data estimates which may be significantly out of date. Verify all prices and metrics before making any decisions.

Never silently substitute training-data estimates for current prices. When in doubt, ask the user to paste the latest quote.

---

📋 Data & Sources Header — Open Every Output With It

Immediately after the not-tax-advice banner (which is always line one), the output carries this provenance block, filled in — never left as placeholders. It is the standard documented on the [Data & Accuracy](https://yennanliu.github.io/InvestSkill/data-and-accuracy.html) page and the first thing `result-validator` looks for:

Data & Sources
  As of:      <date the figures represent, e.g. 2026-06-30>
  Source:     <primary docs — SEC EDGAR 10-K/10-Q, company IR, FRED, exchange data …>
  Retrieval:  <pasted by user | web/tool retrieval | model memory>
  Confidence: <HIGH | MEDIUM | LOW>

• `Retrieval: model memory` must be paired with `Confidence: LOW` — memory is a placeholder until confirmed against a primary source.
• Mixed sources: list each with its own as-of date rather than blending them.
• Sources disagree on the same figure (a closing price, a deal term): prefer the primary source (SEC filing, company release, exchange data) over an aggregator, then the most recent dated one. Show both values with their sources and dates, say which you used and why, and never average them.
• Data the user pasted is reported as `pasted by user`; do not upgrade its confidence beyond what the user's own source supports.

For this skill the `Source:` line must also name the **tax year** and the rule sources used (IRS publications 550 / 519 / 559, the Form W-8BEN instructions, the relevant treaty table) — rules, like prices, have an as-of date.

---

Overview

Every other framework in the catalog stops at the pre-tax number. `stock-eval` says whether to own it, `stock-valuation` what it is worth, `position-ladder` how to build the position, `dividend-analysis` how safe the payout is. None of them answers the question that decides what the investor *keeps*: **what does this trade or this portfolio cost in tax, and is there a cheaper way to do the same thing?**

This skill is that layer. Given a position, a proposed trade, or a whole portfolio with lots and dates, it works through the US mechanics that move the after-tax result — holding period, wash-sale windows, the qualified-dividend test, which lot to sell, whether a loss is worth harvesting and what to swap into, which account each asset belongs in — and estimates the annual **tax drag** the portfolio is carrying. The **`--non-us` module** switches to the rules that apply to a non-resident alien holding US stocks through a US or international broker, which differ completely from what US-centric content teaches and are almost never covered: withholding at source, the treaty rate (or the lack of a treaty), how capital gains are generally treated, the estate-tax exposure that starts far lower than for US persons, and the Irish-domiciled UCITS route many non-US investors use instead.

**What it is not.** It is not a return calculator, a filing tool, or a substitute for a professional. It does not cover state taxes, the alternative minimum tax, employer stock plans (ISOs, ESPPs, RSUs) beyond flagging them, or the investor's home-country taxation in `--non-us` mode. It names the mechanism, shows the arithmetic on the user's own numbers, and says where the professional's judgment has to take over.

---

1. Modes

| Mode | Invocation | Scope | |------|------------|-------| | **Trade** | `tax-lens AVGO — sell 20 sh bought 2026-05-30 @ $128, now $122` | One proposed sale, purchase, or swap: character of the gain/loss, wash-sale check, lot choice, timing alternatives | | **Position** | `tax-lens AVGO` + lots | Every lot of one holding: unrealized gain/loss by