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

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.