Initial commit: OpenSpec setup and stock-deep-evaluation change

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>
2026-08-21 15:35:54 -04:00
commit 73e93e7cb4
30 changed files with 4631 additions and 0 deletions
@@ -0,0 +1,85 @@
+## ADDED Requirements
+
+### Requirement: Ticker search entry point
+
+The web app SHALL present a search input where a user enters an NYSE/Nasdaq ticker
+to request an evaluation. Invalid or unresolvable symbols SHALL produce an inline
+error without navigating away.
+
+#### Scenario: User searches a valid ticker
+- **WHEN** a user enters a resolvable ticker and submits
+- **THEN** the app initiates an evaluation for that ticker
+
+#### Scenario: User searches an invalid ticker
+- **WHEN** a user submits a symbol that does not resolve
+- **THEN** the app shows an inline not-found message and stays on the search view
+
+### Requirement: Evaluation request orchestration
+
+The app SHALL orchestrate the pipeline for a request: fetch market data, run the
+equity-evaluation engine, then invoke the analysis agent, returning both the
+structured evaluation and the written analysis to the client.
+
+#### Scenario: Full pipeline succeeds
+- **WHEN** a valid ticker is evaluated with data and an agent key available
+- **THEN** the app returns the structured evaluation and the written analysis
+
+#### Scenario: Partial pipeline (agent unavailable)
+- **WHEN** market data succeeds but the agent is unavailable
+- **THEN** the app returns the structured evaluation and indicates the narrative is
+  pending
+
+### Requirement: Evaluation report view
+
+The app SHALL render the evaluation as a report with clearly delineated sections:
+current standing, earnings recap and quality-of-earnings caveats, financials and
+segments, valuation and over/undervalued reasoning, macro factors, timing, entry
+levels, exit/targets, stop-loss, bull-versus-bear, the actionable plan, and the
+disclaimer. Tabular data SHALL render as tables and unavailable values SHALL be
+shown as such rather than as zero.
+
+#### Scenario: Report sections rendered
+- **WHEN** an evaluation result is available
+- **THEN** the report view displays each populated section in order
+
+#### Scenario: Unavailable values shown honestly
+- **WHEN** a section contains an unavailable value
+- **THEN** the view displays it as unavailable rather than as a zero or blank number
+
+### Requirement: Price chart with marked levels
+
+The app SHALL render a price chart with the computed moving averages and overlay
+markers for the recommended entry bands, exit/target levels, and stop-loss levels
+so the user can see them against price history.
+
+#### Scenario: Levels overlaid on chart
+- **WHEN** the report renders with computed levels
+- **THEN** the chart shows price history with entry, exit, and stop-loss markers
+
+### Requirement: Loading and error states
+
+The app SHALL show progress while an evaluation runs and SHALL present typed
+errors (data unavailable, rate-limited, agent failed) as user-readable messages
+without blank screens.
+
+#### Scenario: Loading indicator during evaluation
+- **WHEN** an evaluation is in progress
+- **THEN** the app shows a loading state until results or an error return
+
+#### Scenario: Error surfaced to user
+- **WHEN** the pipeline returns a typed error
+- **THEN** the app displays a readable message describing what failed
+
+### Requirement: API key configuration in the app
+
+The app SHALL provide a way to configure the market-data and Anthropic API keys
+via environment/config, SHALL NOT expose secret keys to the browser, and SHALL
+indicate when a required key is missing.
+
+#### Scenario: Keys read server-side only
+- **WHEN** the app calls external providers
+- **THEN** secret keys are used only in server-side code and never sent to the client
+
+#### Scenario: Missing key indicated
+- **WHEN** a required key is absent
+- **THEN** the app indicates which capability is unavailable until the key is set