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

1. Project scaffold

• 1.1 Initialize Next.js (App Router) + TypeScript project at the repo root
• 1.2 Add Tailwind CSS and a base layout/theme (light + dark)
• 1.3 Add a charting library (Recharts or lightweight-charts) and confirm it renders
• 1.4 Set up .env.local handling and .env.example for MARKET_DATA_API_KEY and ANTHROPIC_API_KEY; ensure secrets never reach the client bundle
• 1.5 Configure lint/format/test tooling (ESLint, Prettier, Vitest/Jest) and a passing sample test
• 1.6 Define shared TypeScript types module (normalized data models + Evaluation object skeleton with unavailable markers)

2. Market-data layer (market-data spec)

• 2.1 Define the DataProvider interface and normalized models (CompanyProfile, Fundamentals incl. optional segments, PriceHistory, AnalystCoverage, Estimates), each with asOf + delayed|realtime
• 2.2 Spike two free providers (e.g. FMP, Finnhub) against DE; pick the default based on segment + forward-estimate coverage; record the choice in design Open Questions
• 2.3 Implement the default free-tier provider behind the interface
• 2.4 Implement ticker resolution with NYSE/Nasdaq validation and typed not-found result
• 2.5 Implement a fixture/mock provider seeded from the DE example for tests and offline dev
• 2.6 Add provider-boundary caching (in-memory, TTL, keyed by ticker+dataset) and retry/backoff for rate-limit/transient errors returning typed errors
• 2.7 Unit-test normalization, unavailable-field handling, and error/rate-limit paths

3. Technicals module (market-data spec)

• 3.1 Implement pure functions: 20/50/200-day moving averages, 52-week high/low distance, average volume + today's volume multiple
• 3.2 Implement swing high/low detection and realized (e.g. 60-day annualized) volatility
• 3.3 Handle insufficient-history cases (mark long-window indicators unavailable)
• 3.4 Unit-test all indicators against known values from the DE example

4. Evaluation engine (equity-evaluation spec)

• 4.1 Implement current-standing summary (price, day change abs/%, volume multiple, 52-wk distance, market cap, trailing P/E)
• 4.2 Implement earnings recap (EPS vs consensus, beat/miss, net income YoY, guidance changes) gated by a configurable recency window
• 4.3 Implement quality-of-earnings caveats (one-time items + EPS impact, price-vs-volume, wrong-baseline headline metrics)
• 4.4 Implement financial summary (current vs prior-year) and per-segment breakdown when available
• 4.5 Implement valuation view (TTM EPS, trailing/forward P/E, growth, FCF & dividend yield, vs own history) with conflicting-estimate reconciliation
• 4.6 Implement explicit over/undervalued reasoning (multiple-expansion vs earnings-growth, trough/peak earnings)
• 4.7 Implement macro/sector factor analysis (tariffs trajectory, rates, input-cost pressure, peer read-throughs)
• 4.8 Implement timing/volatility context (post-earnings behavior, implied vs actual move, monthly ranges, gap-fill status)
• 4.9 Implement entry levels (ranked levels with meaning, % below price, implied multiple at each) grouped into bands with starter/high-conviction tranches
• 4.10 Implement exit/targets (analyst avg/median/range + technical resistance) and stop-loss levels (technical/volatility-based, concrete prices + rationale)
• 4.11 Implement bull-vs-bear synthesis and actionable plan (tranche sizing, next dated catalyst, conditional rules, one metric to watch)
• 4.12 Emit the typed Evaluation object with explicit unavailable markers (no fabrication) + mandatory disclaimer
• 4.13 Unit-test each section, including missing-input and unavailable-value paths, seeded from the DE example

5. Analysis agent (analysis-agent spec)

• 5.1 Define the AnalysisAgent interface (input: Evaluation; output: narrative sections)
• 5.2 Implement the Claude default via @anthropic-ai/sdk (current model), key loaded server-side from config
• 5.3 Design the prompt + structured/JSON output so narrative maps to spec sections and uses ONLY supplied figures
• 5.4 Preserve input caveats/discrepancies and enforce the disclaimer in the narrative
• 5.5 Implement graceful degradation when no key is set (return structured evaluation, mark narrative unavailable)
• 5.6 Implement typed agent error handling (auth/rate-limit/timeout) that retains the computed evaluation
• 5.7 Test grounding (every cited figure exists in input), no-key, and error paths with a mock agent

6. Pipeline + API (evaluation-app spec)

• 6.1 Implement server-side route/action orchestrating resolve → data → evaluate → agent, returning { evaluation, narrative | error }
• 6.2 Handle partial results (data ok / agent unavailable) and typed errors end-to-end
• 6.3 Ensure secret keys are used only server-side and surface missing-key state per capability

7. Web UI (evaluation-app spec)

• 7.1 Build the ticker search entry point with inline invalid/not-found handling
• 7.2 Build the report view rendering every section in order, tables as tables, unavailable values shown honestly
• 7.3 Build the price chart with moving averages and overlay markers for entry bands, exit/targets, and stop-loss levels
• 7.4 Implement loading state and readable error states (no blank screens)
• 7.5 Surface missing-key indicators and a settings/config affordance for keys

8. Verification

• 8.1 End-to-end run on DE (with keys) producing a report structurally matching the example; note any data gaps from the free tier
• 8.2 End-to-end run with no agent key confirming structured evaluation still renders
• 8.3 Run the full test suite and lint; confirm green
• 8.4 Update README with setup, env vars, provider choice, and run instructions
• 8.5 Run openspec validate stock-deep-evaluation and archive the change when complete