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>
75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
## 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
|