equitysearch/openspec/changes/stock-deep-evaluation/proposal.md

## Why

Retail and semi-professional investors lack a single tool that turns raw market
data into a clear, defensible thesis on whether an NYSE/Nasdaq-listed company is
over- or undervalued, why, and how to act on it. Existing screeners show numbers
but not judgment; existing chat tools give judgment but aren't wired to live
fundamentals, technicals, and macro context. This change delivers the foundation:
a web app that, given a single ticker, produces a thorough, agent-written
evaluation covering valuation drivers, macro factors, entry/exit points, and
stop-loss levels — with a data layer and agent interface designed to grow.

## What Changes

- Introduce a **Next.js + TypeScript web app** where a user searches a single
  NYSE/Nasdaq ticker and receives a full evaluation report.
- Introduce a **pluggable market-data layer**: a `DataProvider` interface plus a
  default free-tier provider, returning normalized company fundamentals, price
  history, and technical indicators. Paid providers can be swapped in later with
  no changes to consumers.
- Introduce an **equity-evaluation engine** that computes and explains: valuation
  (the specific reasons a company looks over- or undervalued), relevant macro
  factors affecting the stock, candidate entry and exit points, and suggested
  stop-loss levels.
- Introduce a **pluggable analysis-agent layer** backed by **Claude via the
  Anthropic SDK** (bring-your-own API key) that synthesizes the structured data
  into a written investment thesis and the reasoning behind each recommendation.
  The default model is **Claude Opus 4.8**, with a per-ticker "deep dive" option
  that escalates to **Claude Fable 5** for the hardest analyses.
- Give the agent **live web grounding** (Anthropic's server-side web search and
  web fetch) so macro/news facts the structured data layer lacks — tariff and rate
  developments, analyst rating/target changes, management commentary, peer
  read-throughs, dated catalysts — are sourced and attributed, matching the depth
  of the reference evaluation.
- Introduce **cost controls**: capture per-report token/search usage, compute its
  cost from a configurable price table, track month-to-date spend, and enforce a
  configurable monthly budget (warn on a soft threshold, block on the cap) so the
  agent — especially the Fable 5 deep dive — can't run up a surprise bill.
- Make the data models and evaluation engine **instrument-type-aware** (equity vs.
  ETF) from the start. v1 builds the **equity** branch only; the ETF branch
  (holdings, expense ratio, NAV premium/discount, weighted fundamentals) is a
  fast-follow change that slots into the existing seams without a refactor.
- Scope v1 to **single-ticker deep evaluation** of individual equities. Deferred to
  later changes: the ETF evaluation branch, a **screening / candidate-finder** mode
  (criteria → grounded shortlist that feeds this evaluator), watchlist monitoring,
  alerts, and multi-ticker dashboards.

## Capabilities

### New Capabilities

- `market-data`: A provider-agnostic data layer. Defines the `DataProvider`
  interface and normalized data models (company profile, fundamentals/financials,
  price history, computed technical indicators), plus a default free-tier
  implementation and configuration for selecting a provider.
- `equity-evaluation`: The core analysis engine. Derives valuation signals and
  the reasons behind over/undervaluation, identifies macro factors affecting the
  stock, and computes candidate entry/exit points and stop-loss levels from price
  and volatility data. Produces a structured evaluation object consumed by the
  agent and UI.
- `analysis-agent`: A provider-agnostic agent interface with a default Claude
  (Anthropic SDK) implementation. Takes the structured evaluation as context and
  produces a written thesis: the over/undervalued argument, macro narrative, and
  entry/exit/stop-loss rationale. Handles API-key configuration and graceful
  degradation when no key is present.
- `evaluation-app`: The Next.js web application shell and UI. Ticker search,
  request orchestration (data → evaluation → agent), and the report view that
  presents fundamentals, valuation reasoning, macro factors, a price chart with
  marked entry/exit/stop-loss levels, and the agent's written thesis.
- `cost-controls`: Per-report usage capture and cost computation from a
  configurable price table, running spend aggregation, and a configurable monthly
  budget guard (soft-threshold warning, hard-cap block) with the numbers surfaced
  in the UI.

### Modified Capabilities

<!-- None — this is a greenfield project; no existing specs to modify. -->

## Impact

- **New project scaffold**: Next.js + TypeScript app, Tailwind for UI, a charting
  library (e.g. Recharts) for price/technical visualization.
- **New dependencies**: `@anthropic-ai/sdk` for the analysis agent; an HTTP client
  and one free-tier market-data provider SDK/endpoint for the default provider.
- **Configuration/secrets**: environment variables for the market-data API key(s)
  and the Anthropic API key; both treated as bring-your-own and never committed.
- **External services**: one market-data API (rate-limited free tier by default)
  and the Anthropic API. Both isolated behind interfaces so cost/provider choices
  can change without touching evaluation or UI code.
- **Not affected / deferred**: persistence, user accounts, watchlists, real-time
  streaming, alerting, and backtesting are out of scope for this change.