Equity Timing Lab

• 

  1. The problem and promise: Compare selling now with the next holding milestone—without turning the result into a recommendation.

• 

  2. The ESPP decision threshold: The engine finds the lowest future price at which waiting matches or exceeds the proposed-sale outcome.

• 

  3. (1) Transparent scenario comparison: Every scenario is independently calculated using source-backed 2025 federal and California rules.

• 

  3. (2) Transparent scenario comparison: Every scenario is independently calculated using source-backed 2025 federal and California rules.

• 

  4. Governed GPT-5.6 explanation: GPT-5.6 selects only applicable, approved explanation blocks; the deterministic engine financial value.

• 

  5. (1) Breadth and usability (desktop): The same governed workflow supports vested RSUs and works across desktop and mobile.

• 

  5. (2) Breadth and usability (mobile): The same governed workflow supports vested RSUs and works across desktop and mobile

OpenAI Build Week Hackathon related project

Inspiration

Employees often know that waiting may improve the tax treatment of an equity sale, but that is only half the decision. Waiting also exposes the shares to market risk. Traditional tax tools explain classifications and calculate taxes. Generic AI may provide fluent but unverifiable advice. Neither clearly answers the practical question: How far could the stock fall before the modeled tax benefit of waiting disappears?

What it does

The application:

1. Models a proposed ESPP or vested-RSU sale.
2. Compares it with the first relevant holding milestone.
3. Calculates incremental federal ordinary-income tax, preferential capital-gain tax, NIIT, and California tax.
4. Finds the lowest cent-level future stock price at which the wait scenario’s estimated net proceeds meet or exceed the proposed-sale outcome.
5. Shows the proposed and wait scenarios, tax drivers, official sources, assumptions, and limitations.
6. Optionally asks GPT-5.6 to explain the verified result without authoring financial values or making a sell, hold, buy, or wait recommendation.

How we built it

Equity Timing Lab separates authoritative computation from probabilistic explanation. The implementation includes:

1. A deterministic TypeScript calculation engine.
2. Source-backed ESPP and vested-RSU state machines.
3. A versioned Verified Result contract.
4. A source-backed 2025 federal and California tax profile.
5. High-precision decimal arithmetic with independently rounded two-decimal display values.
6. A cent-level break-even solver with explicit verification at the returned price and one cent below it.
7. A server-only OpenAI Responses API integration using GPT-5.6 and Structured Outputs.
8. A minimized verified-value catalog that prevents GPT-5.6 from authoring financial values.
9. A centralized applicability policy, independent semantic verification, deterministic rendering, and deterministic fallback.
10. A responsive and accessible Vinext/Next.js interface deployed through OpenAI Sites.

I used Codex throughout the project to help translate tax-rule decisions into versioned contracts, design the calculation architecture, implement the engine and UI, build the test suite, investigate defects, audit privacy and dependency risks, and complete deployment.

I retained the key product decisions: limiting the supported scope, choosing the approved tax-rule interpretations, separating exact and displayed values, keeping the output neutral, and defining the bounded role of GPT-5.6.

Challenges we ran into

Translating tax authority into deterministic software Tax rules are written for human interpretation, not as executable specifications. I needed to define explicit date boundaries, compensation and basis rules, capital character, selling-fee treatment, and unsupported states. Each implemented rule had to map to an official source and behave consistently at edge cases such as anniversary dates, leap years, fractional shares, and capital losses.

Defining the break-even threshold correctly The break-even result could not be produced by a simple fixed-rate formula because the complete tax scenario changes across brackets, capital-gain stacking, NIIT thresholds, and California rules. The solver therefore evaluates the complete wait scenario on an integer-cent price grid.

Preserving precision without overwhelming the user Financial calculations must reconcile exactly, but users expect monetary values to display as dollars and cents. The engine retains high-precision decimal values for calculations, comparisons, and reconciliation while every user-facing monetary value is rendered with explicit half-up two-decimal formatting.

Building trust without turning the product into advice The application needed to explain a complicated financial trade-off while refusing to make the decision for the user. This required neutral language, official-source links, visible limitations, synthetic sample data, and an explicit educational-use disclaimer.

Delivering within a short timeline I learned about OpenAI Build Week only three to four days before the deadline. Codex made it possible to move from problem definition and architecture through implementation, testing, audit, responsive design, and deployment without abandoning the correctness and governance requirements.

Accomplishments that we're proud of

Successfully completed Codex project and used it throughout architecture, implementation, testing, audits, and deployment.

Equity Timing Lab deliberately provides a comparison rather than a sell, hold, buy, or wait recommendation. **Deterministic computation decides the numbers; probabilistic intelligence explains them.

Built With

• claudflare
• codex
• gpt5.6
• javascript
• nextjs
• openai