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>
6.2 KiB
Context
This is a greenfield Next.js + TypeScript web app that turns a single NYSE/Nasdaq
ticker into a thorough, agent-written evaluation (valuation, macro, entry/exit,
stop-loss). The target output shape is captured concretely in
examples/de-reentry-2026-08-21.md and encoded as requirements in the four spec
files. Constraints: bring-your-own API keys, free-tier market data by default,
rate limits, and no persistence in v1. The design must keep data-provider and
model-provider choices swappable so cost/quality decisions don't ripple into the
evaluation or UI code.
Goals / Non-Goals
Goals:
- One typed pipeline:
resolve ticker → fetch data → compute evaluation → agent narrative. - Provider-agnostic boundaries:
DataProviderandAnalysisAgentinterfaces are the only seams consumers see. - Deterministic, testable evaluation math separated from the non-deterministic agent prose. The structured evaluation must stand on its own even with no agent key.
- Secrets stay server-side only.
Non-Goals:
- Persistence, accounts, watchlists, alerts, real-time streaming, backtesting.
- Multi-ticker dashboards. (Deferred to later changes.)
- Trade execution or brokerage integration.
Decisions
D1 — App structure: Next.js App Router, server-side data/agent calls
Route handlers (or server actions) under app/api/* run the pipeline server-side;
the client is a thin report view. Rationale: keeps API keys off the browser
(satisfies the app-config spec), and lets data + agent calls share one request.
Alternative considered: client-side fetching — rejected because it would leak keys
and duplicate rate-limit handling.
D2 — DataProvider interface with a free default
A single interface returns normalized models: CompanyProfile, Fundamentals
(TTM + per-FY, optional segments), PriceHistory, TechnicalContext (computed),
AnalystCoverage, Estimates. Default implementation targets a free tier
(candidate: Financial Modeling Prep or Finnhub; final pick during tasks). Each
model carries an asOf timestamp and delayed|realtime flag. Alternative:
code directly against one vendor — rejected for lock-in and testability.
D3 — Technical indicators computed in-house, not taken from the provider
Moving averages (20/50/200), swing highs/lows, 52-week distance, volume multiple,
and realized volatility are computed from OHLCV in a pure technicals module.
Rationale: providers expose these inconsistently; in-house math is deterministic
and unit-testable, and it is the same input the entry/exit/stop logic needs.
D4 — Evaluation engine is pure and provider-free
evaluate(inputs) → Evaluation is a pure function over normalized data. It emits
a typed Evaluation object (one field per spec section) with explicit
unavailable markers — never fabricated or zero-filled values. All entry/exit/
stop levels, implied multiples at each level, and valuation reasoning are computed
here. Rationale: the spec requires the structured object to be consumable without
the agent, and pure functions make the many numeric requirements testable.
D5 — AnalysisAgent interface; Claude default via @anthropic-ai/sdk
The agent takes the Evaluation object and returns narrative sections. Default
impl calls a current Claude model, instructed to use ONLY the supplied figures,
preserve any flagged caveats/discrepancies, and include the disclaimer. Structured
output (tool/JSON schema) is preferred so the UI can render narrative per section.
Alternative: free-text prompt with the raw data — rejected because grounding and
per-section rendering are weaker. When no key is set, the pipeline returns the
Evaluation with narrative: unavailable.
D6 — Typed results end-to-end; errors are values
Data, evaluation, and agent layers return typed results/errors (not thrown exceptions across boundaries). A data failure, rate-limit, or agent failure each degrade to a partial result the UI can render. Rationale: the specs require honest partial states and readable errors.
D7 — Caching and rate limiting at the provider boundary
An in-memory (v1) cache keyed by ticker+dataset with short TTLs sits inside the provider layer, with retry/backoff for transient/rate-limit errors. Rationale: free tiers are tightly limited; caching one evaluation's repeated reads avoids burning quota. Persistence-backed cache is a later change.
Risks / Trade-offs
- [Free-tier data is delayed/incomplete — segments, estimates, or history may be missing] → Normalized models mark fields unavailable; evaluation and UI render honestly; provider is swappable for a paid tier without consumer changes.
- [Agent may hallucinate numbers] → Agent receives only the structured object, is instructed to cite nothing outside it, and prose is rendered alongside the computed tables so drift is visible; consider a post-check that every cited figure exists in the input.
- [Rate limits during development/demo] → Caching + backoff; a fixture/mock provider for tests and offline work.
- [Numeric correctness of valuation/technical math] → Pure modules with unit tests seeded from the DE example's known figures.
- [Not financial advice / liability] → Mandatory disclaimer enforced in both the evaluation object and the agent narrative.
Migration Plan
Greenfield — no data migration. Deployment: run locally (localhost:3000) with
.env.local holding the market-data and Anthropic keys. Rollout is incremental by
capability (see tasks): scaffold → data layer + technicals → evaluation engine →
agent → UI. Rollback is trivial (no persisted state). Keys are provided via env;
absence degrades gracefully rather than failing the build.
Open Questions
- Which free market-data provider is the default (coverage of segments + forward
estimates varies materially)? Resolve early in tasks by spiking 2 providers on
DE. - Source of options-implied expected move and forward consensus EPS on free tiers — may need a secondary source or graceful omission.
- Preferred charting library (Recharts vs. lightweight-charts) for overlaying entry/exit/stop markers on price history.
- Whether to add an automated "every cited figure exists in inputs" guard on agent output in v1 or defer to a later hardening change.