equitysearch/openspec/changes/stock-deep-evaluation/specs/equity-evaluation/spec.md

## ADDED Requirements

### Requirement: Current standing summary

The system SHALL produce a current-standing summary for the ticker containing:
last price, absolute and percent change on the day, today's volume as a multiple
of average, percent distance from the 52-week high and low, market capitalization,
and trailing P/E.

#### Scenario: Standing summary is produced
- **WHEN** an evaluation is run for a resolved ticker with price and fundamentals
- **THEN** the output includes price, day change (abs and %), volume multiple,
  distance from 52-week high and low, market cap, and trailing P/E

### Requirement: Earnings recap when a recent report exists

The system SHALL, when the most recent quarterly report falls within a
configurable recency window, produce an earnings recap comparing reported EPS to consensus
(beat/miss and magnitude), net income and its year-over-year change, and any
changes to management guidance.

#### Scenario: Recent earnings summarized
- **WHEN** the latest earnings report falls within the recency window
- **THEN** the output includes EPS actual vs consensus, the beat/miss magnitude,
  net income with YoY change, and guidance changes when available

#### Scenario: No recent earnings
- **WHEN** no report falls within the recency window
- **THEN** the earnings recap is omitted and the evaluation proceeds

### Requirement: Quality-of-earnings caveats

The system SHALL surface quality-of-earnings caveats when the data supports them,
including one-time items (e.g. tax or tariff refunds), price-driven versus
volume-driven revenue changes, and headline metrics that compare against the
wrong baseline (e.g. an equipment-sales figure presented as total revenue).

#### Scenario: One-time item flagged
- **WHEN** a reported result includes a disclosed one-time benefit or charge
- **THEN** the evaluation notes the item and its approximate EPS impact when known

#### Scenario: Price-vs-volume distinction made
- **WHEN** segment or company data separates price realization from volume change
- **THEN** the evaluation states how much of a revenue or profit move came from
  price versus units

### Requirement: Financial and segment breakdown

The system SHALL present a financial summary comparing the current period to the
prior-year period (revenue, operating profit, margins, diluted EPS, operating
and free cash flow) and, where segment data exists, a per-segment breakdown of
revenue, year-over-year change, operating profit, and operating margin versus the
prior-year margin.

#### Scenario: Current-vs-prior financials presented
- **WHEN** current and prior-year period data are available
- **THEN** the output includes a side-by-side comparison of the listed metrics

#### Scenario: Segment breakdown presented when available
- **WHEN** the provider supplies segment data
- **THEN** the output includes per-segment revenue, YoY, operating profit, and
  margin versus the prior-year margin

### Requirement: Valuation analysis with over/undervalued reasoning

The system SHALL compute a valuation view (TTM diluted EPS, trailing P/E, forward
EPS and forward P/E from consensus, net-income and revenue growth, FCF yield,
dividend yield) and compare current multiples against the company's own history.
It SHALL state explicit, data-grounded reasons the company appears overvalued or
undervalued, distinguishing multiple expansion from earnings growth and noting
whether a high multiple sits on trough or peak earnings.

#### Scenario: Valuation metrics computed
- **WHEN** fundamentals and consensus estimates are available
- **THEN** the output includes trailing P/E, forward P/E, growth rates, FCF yield,
  and dividend yield, plus a comparison to prior fiscal-year multiples

#### Scenario: Explicit valuation reasoning produced
- **WHEN** the valuation view is produced
- **THEN** the output states specific reasons for the over/undervalued conclusion
  (e.g. "paying 29x a forecast recovery year before units confirm it")

#### Scenario: Conflicting estimate feeds are reconciled
- **WHEN** two estimate sources disagree on a forward figure
- **THEN** the evaluation discloses the discrepancy and states which figure it used

### Requirement: Macro and sector factor analysis

The system SHALL identify macro and sector factors affecting the stock, such as
tariffs and their year-over-year trajectory, interest-rate sensitivity, commodity
or input-cost pressure on customers, and read-throughs from peer companies.

#### Scenario: Macro factors surfaced
- **WHEN** an evaluation is run
- **THEN** the output lists the material macro/sector factors and their direction
  of impact on the stock

### Requirement: Timing and volatility context

The system SHALL provide timing context: how the stock has historically behaved
after earnings prints, today's move versus the options-implied expected move,
recent monthly trading ranges, and whether a post-earnings gap has been filled.

#### Scenario: Post-earnings behavior characterized
- **WHEN** historical prices around prior earnings dates are available
- **THEN** the output summarizes the typical post-earnings move and how the current
  move compares to the implied expectation

#### Scenario: Gap-fill status reported
- **WHEN** the latest session gapped from the prior close
- **THEN** the output states whether the gap was filled intraday

### Requirement: Entry points

The system SHALL produce a ranked set of candidate entry levels derived from
technical structure (moving averages, swing lows, pre-earnings shelves), each
annotated with what the level represents, its percent distance below the current
price, and the valuation multiple implied at that price. It SHALL group nearby
levels into practical entry bands.

#### Scenario: Entry levels table produced
- **WHEN** technical context and valuation are available
- **THEN** the output includes candidate entry levels with their meaning, distance
  below current price, and implied multiple at that price

#### Scenario: Entry bands recommended
- **WHEN** multiple levels cluster within a narrow range
- **THEN** the output groups them into a band and identifies a starter versus a
  high-conviction tranche

### Requirement: Exit points and price targets

The system SHALL produce candidate exit levels and price targets, incorporating
analyst target average/median/range and technical resistance such as prior highs.

#### Scenario: Exit targets produced
- **WHEN** analyst targets and price history are available
- **THEN** the output includes exit/target levels with their basis and upside from
  the current price

### Requirement: Stop-loss levels

The system SHALL recommend stop-loss levels grounded in technical structure and
realized volatility (e.g. below a key moving average or swing low, or a
volatility-based distance), stated as concrete prices with rationale.

#### Scenario: Stop-loss recommended
- **WHEN** an entry band is identified
- **THEN** the output states a concrete stop-loss price for that entry and the
  technical/volatility basis for it

### Requirement: Bull-versus-bear synthesis and actionable plan

The system SHALL synthesize a bull case and a bear case as explicit lists, and
produce an actionable plan: tranche sizing across entry bands, the next dated
catalyst, conditional logic tying action to observable levels/dates, and the
single most important metric to watch.

#### Scenario: Bull and bear cases produced
- **WHEN** an evaluation is run
- **THEN** the output includes distinct bull and bear point lists grounded in the data

#### Scenario: Actionable plan produced
- **WHEN** entry, exit, and stop levels are available
- **THEN** the output includes tranche guidance, the next dated catalyst, at least
  one conditional rule, and the key metric to monitor

### Requirement: Not-advice disclaimer

Every evaluation SHALL include a clear disclaimer that the output is analysis and
not investment advice.

#### Scenario: Disclaimer present
- **WHEN** any evaluation is produced
- **THEN** the output includes an analysis-not-advice disclaimer

### Requirement: Structured evaluation object

The system SHALL emit the evaluation as a typed, structured object (not only prose)
so the UI and the analysis agent can consume individual sections. Missing inputs
SHALL be represented explicitly rather than fabricated.

#### Scenario: Structured object emitted
- **WHEN** an evaluation completes
- **THEN** a typed object containing each section is available to consumers

#### Scenario: Missing data is not fabricated
- **WHEN** a required input for a section is unavailable
- **THEN** that section marks the value unavailable rather than inventing one