Vision and requirements

Vision

Help someone with ESPP shares understand **how a purchase-and-sale is characterized** for U.S. federal tax purposes — ordinary income vs. capital gain, qualifying vs. disqualifying disposition, basis, and a **simplified dollar estimate** — before they talk to a tax professional.

The product is an educational planner, not a filing tool and not tax advice.

Who it is for

• ESPP participant (employee): Enter one lot (offer, purchase, sale, rates) and see a readable report
• Library consumer: Call `espp_tax` from Python without the web UI
• Maintainer / agent: Keep tax math in one place and keep this document honest

In scope

1. Model a **single purchase lot** and a **sale of some or all** of those shares.
2. Apply Section 423 holding rules (2 years from offer start, 1 year from purchase).
3. Characterize ordinary income, cost basis, and capital gain using the IRS **lesser-of** rule on qualifying dispositions.
4. Optionally estimate tax dollars from user-supplied **marginal** rates.
5. Make the report verbose enough to audit: inputs, derived prices, disposition, characterization, narrative.
6. Stay deployable as a small FastAPI app on Vercel with no accounts or stored user data.

Out of scope

• A complete Form 1040, Schedule D, Form 6251, or AMT credit worksheet
• NIIT, wash sales, loss netting against ordinary income
• Multiple lots, FIFO, or specific identification
• ISO / NSO overlap or payroll withholding detail
• State-specific ESPP statutes beyond one marginal state rate
• Persistence, auth, or multi-user workspace
• Live market quotes or brokerage imports

Shipped requirements

21 functional, 7 non-functional, and 13 UX requirements are marked Shipped. IDs and status live in the GitHub document.

Constraints

• Educational disclaimer must remain visible (header and footer).
• Plan documents and employer W-2 treatment can differ from the model; the UI must not imply otherwise.
• Holding-period “2 years” is implemented as 730 days from offer start.