paulandClaude Opus 4.8
73e93e7cb4
Set up OpenSpec spec-driven workflow and fully specify the first change, stock-deep-evaluation: a Next.js/TS app for thorough single-stock evaluation (valuation reasoning, macro factors, entry/exit points, stop-loss) with a pluggable data layer and Claude analysis agent. Includes proposal, design, specs (market-data, equity-evaluation, analysis-agent, evaluation-app), tasks, and the DE gold-standard example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4.7 KiB
ADDED Requirements
Requirement: Provider-agnostic data interface
The system SHALL define a DataProvider interface that all market-data access
goes through. Evaluation and UI code MUST depend only on this interface and its
normalized data models, never on a concrete provider SDK or response shape. The
active provider SHALL be selectable via configuration without code changes in
consumers.
Scenario: Default free provider is used when none configured
- WHEN the app starts with no market-data provider explicitly configured
- THEN a default free-tier provider implementation is selected
- AND all normalized data models are populated from that provider
Scenario: Provider can be swapped via configuration
- WHEN an operator sets the provider configuration to a different implementation
- THEN the system routes all data requests through the new provider
- AND no changes to evaluation or UI code are required
Requirement: Ticker resolution for NYSE and Nasdaq
The system SHALL accept a ticker symbol, validate that it resolves to an NYSE- or Nasdaq-listed equity, and return a normalized company profile (name, exchange, sector/industry, currency, shares outstanding).
Scenario: Valid listed ticker resolves
- WHEN a user submits a ticker listed on NYSE or Nasdaq (e.g.
DE) - THEN the system returns a company profile with name, exchange, and sector
Scenario: Unknown or unlisted ticker is rejected
- WHEN a user submits a symbol that does not resolve to an NYSE/Nasdaq equity
- THEN the system returns a not-found result with a clear message
- AND no evaluation is attempted
Requirement: Company fundamentals and financial statements
The system SHALL provide normalized fundamentals sufficient for valuation and earnings analysis: TTM and per-fiscal-year revenue, operating profit, margins, net income, diluted EPS, operating cash flow, free cash flow, dividend per share, and total/net debt. Where the provider exposes it, per-segment revenue and operating profit SHALL be included.
Scenario: Fundamentals returned for a resolved ticker
- WHEN fundamentals are requested for a resolved ticker
- THEN the system returns TTM and at least the last three fiscal years of the listed metrics
- AND each metric carries the fiscal period it belongs to
Scenario: Missing metric is represented explicitly
- WHEN the provider does not supply a given metric
- THEN the normalized model marks that metric as unavailable rather than zero
Requirement: Price history and computed technical indicators
The system SHALL provide daily OHLCV price history and compute technical context used for timing: 20/50/200-day moving averages, recent swing highs and lows, distance from 52-week high and low, average daily volume and today's volume as a multiple of it, and realized volatility (e.g. 60-day annualized).
Scenario: Technical context computed from price history
- WHEN price history is requested for a resolved ticker
- THEN the system returns the moving averages, 52-week high/low, volume ratio, and realized volatility computed from that history
Scenario: Insufficient history degrades gracefully
- WHEN fewer than 200 trading days of history are available
- THEN longer-window indicators (e.g. 200-day average) are marked unavailable
- AND shorter-window indicators are still returned
Requirement: Analyst coverage and consensus estimates
The system SHALL provide, where available, analyst rating counts (bullish / neutral / bearish), average and median price targets, target range, and forward consensus estimates (next fiscal-year EPS and revenue).
Scenario: Analyst data returned when available
- WHEN analyst coverage exists for a ticker
- THEN the system returns rating counts, average/median/target range, and forward EPS/revenue estimates
Scenario: No coverage is handled
- WHEN no analyst coverage exists for a ticker
- THEN the system returns an empty coverage result the evaluation can note
Requirement: Rate limiting, caching, and data-freshness disclosure
The system SHALL respect provider rate limits, cache responses to reduce calls, and expose each dataset's freshness (as-of timestamp and whether it is delayed or real-time) so downstream output can disclose it.
Scenario: Rate-limit and transient errors are handled
- WHEN the provider returns a rate-limit or transient error
- THEN the system retries within limits and, if still failing, returns a typed error rather than throwing an unhandled exception
Scenario: Data freshness is surfaced
- WHEN any dataset is returned
- THEN it includes an as-of timestamp and a delayed/real-time flag