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>
3.3 KiB
ADDED Requirements
Requirement: Provider-agnostic analysis-agent interface
The system SHALL define an AnalysisAgent interface that accepts a structured
evaluation object and returns a written analysis. Consumers MUST depend only on
this interface so the underlying model provider can change without affecting the
evaluation engine or UI.
Scenario: Agent invoked through the interface
- WHEN an evaluation object is passed to the configured analysis agent
- THEN the agent returns a written analysis produced through the interface
Scenario: Alternate implementation can be registered
- WHEN a different agent implementation is configured
- THEN the system uses it without changes to evaluation or UI code
Requirement: Claude default implementation via Anthropic SDK
The system SHALL ship a default AnalysisAgent backed by Claude through the
@anthropic-ai/sdk, targeting a current Claude model. The API key SHALL be
supplied by the user (bring-your-own-key) via configuration and never hard-coded
or committed.
Scenario: Claude produces the written thesis
- WHEN a valid Anthropic API key is configured and an evaluation is submitted
- THEN the default agent calls Claude and returns the written thesis
Scenario: Key sourced from configuration
- WHEN the app reads its configuration
- THEN the Anthropic API key is loaded from environment/config, not source code
Requirement: Grounded, structured written analysis
The agent SHALL base its narrative only on the supplied evaluation data and SHALL NOT invent figures. It SHALL produce the narrative sections reflected in the example evaluation: current standing, earnings recap and quality-of-earnings caveats, valuation with explicit over/undervalued reasoning, macro factors, timing, entry/exit/stop-loss rationale, bull-versus-bear, and an actionable plan. When a data caveat or discrepancy is present in the input, the agent SHALL preserve it.
Scenario: Narrative grounded in provided data
- WHEN the agent writes the analysis
- THEN every figure it cites is present in the supplied evaluation object
Scenario: Data caveats preserved
- WHEN the evaluation object flags a discrepancy or one-time item
- THEN the written analysis surfaces that caveat rather than omitting it
Scenario: Disclaimer preserved in narrative
- WHEN the agent returns its analysis
- THEN the analysis-not-advice disclaimer is present
Requirement: Graceful degradation without an API key
When no analysis-agent key is configured, the system SHALL still return the full structured evaluation and SHALL clearly indicate that the written narrative is unavailable until a key is provided.
Scenario: No key configured
- WHEN an evaluation is requested and no agent API key is configured
- THEN the structured evaluation is returned
- AND the response indicates the written analysis is unavailable pending a key
Requirement: Agent error handling
The system SHALL handle agent failures (auth errors, rate limits, timeouts) by returning a typed error and the underlying structured evaluation, without losing the data already computed.
Scenario: Agent call fails
- WHEN the agent call errors after retries
- THEN the system returns the structured evaluation plus a typed agent error
- AND the computed data is not discarded