TradingAgents/docs/superpowers/specs/2026-03-24-senior-analysis-integration-design.md

# Senior Analysis Integration Design

**Date:** 2026-03-24

**Goal**

Upgrade TradingAgents into a senior-level research system by salvaging selected upstream PRs, adding structured underwriting roles for stocks, integrating the full Polymarket module, and standardizing final outputs under a concise chief-analyst summary layer.

## Scope

This design covers:

- Salvage and integration of upstream PRs:
  - `#401` role-based LLM routing
  - `#244` Macro Analyst
  - `#399` social sentiment tool
  - `#359` Factor Rule Analyst
  - `#392` medium-term positioning upgrade
  - `#452` Chief Analyst supervisor
  - `#432` full Polymarket module
- New stock-analysis roles:
  - `Valuation Analyst`
  - `Segment Analyst`
  - `Scenario & Catalyst Analyst`
  - `Position Sizing Analyst`
- Isolation of all work in in-repo git worktrees and branches
- Push of resulting branches to the `guanghan` fork

## Non-Goals

- No direct order placement or brokerage execution
- No attempt to preserve each PR verbatim if it conflicts with current `main`
- No change to the current dirty local checkout on `main`

## Constraints

- The current repository contains local uncommitted work on `main`; all integration must happen in isolated worktrees.
- Upstream PRs overlap on graph wiring, config, state schema, CLI flows, and reporting.
- Several upstream PRs are closed without merge, so behavior must be salvaged rather than blindly cherry-picked.

## Integration Strategy

Use a phased branch family instead of a single large merge:

1. `integration/upstream-stock`
   - Salvage `#401`, `#244`, `#399`, `#359`, `#392`
   - Stabilize the stock pipeline and shared infrastructure
2. `integration/senior-stock-roles`
   - Add new structured stock roles
   - Upgrade stock outputs from verbose prose to machine-readable underwriting artifacts plus short human summaries
3. `integration/polymarket-full`
   - Merge full `#432` on a clean parallel branch
   - Keep prediction-market architecture parallel to stocks
4. `integration/chief-analyst-final`
   - Salvage `#452`
   - Reconcile final summary/reporting behavior across stocks and Polymarket
5. `integration/final`
   - Final conflict resolution, CLI/reporting cleanup, validation, and push-ready polish

## Stock Pipeline Target Architecture

### Core Analysts

- `market`
- `social`
- `news`
- `fundamentals`
- `macro`
- `factor_rule` optional

### Senior Underwriting Analysts

- `valuation`
  - fair value range
  - reverse DCF / expectation check
  - comp-based valuation sanity check
  - expected return profile
- `segment`
  - business unit decomposition
  - segment economics
  - value-driver map
- `scenario_catalyst`
  - bull/base/bear cases
  - probabilities
  - dated catalyst map
  - thesis invalidation triggers
- `position_sizing`
  - conviction tier
  - target weight
  - initial size
  - add/trim/exit bands
  - max loss / risk budget

### Synthesis Layer

- Bull and bear researchers consume all analyst outputs
- Research manager produces a structured investment plan
- Risk debate argues over explicit scenario, valuation, and sizing fields instead of re-paraphrasing prose
- Portfolio manager produces the canonical action recommendation

### Final Compression Layer

- `Chief Analyst`
  - reads full final state
  - emits concise structured output
  - validates that the final recommendation matches supporting evidence

Required top-level output fields:

- `verdict`
- `fair_value`
- `catalysts`
- `execution`
- `tail_risk`
- `variant_perception`

## Polymarket Target Architecture

Adopt `#432` as a parallel product module rather than forcing it into the stock graph.

Shared conventions that should be standardized across both products:

- role-based LLM routing
- structured final recommendation schema
- chief-analyst summary format
- report/export conventions
- sizing vocabulary

## Data Model Changes

The current stock system primarily passes long text reports between nodes. That is the main reason downstream reasoning becomes repetitive and weakly quantitative.

Each senior stock role must emit:

1. a structured machine-readable object for downstream nodes
2. a short markdown summary for saved reports

Examples:

- `valuation_report` + `valuation_data`
- `segment_report` + `segment_data`
- `scenario_catalyst_report` + `scenario_catalyst_data`
- `position_sizing_report` + `position_sizing_data`

Research manager, portfolio manager, and chief analyst must consume the structured fields first and use report text only as supporting narrative.

## Expected Quality Gains

This design directly addresses the current weaknesses:

- financial modeling: `valuation`
- scenario analysis: `scenario_catalyst`
- concision: `chief analyst`
- segment breakdown: `segment`
- peer comp: `#392` plus `valuation`
- catalyst dating: `scenario_catalyst`
- sizing framework: `position_sizing`
- technical-fundamental integration: richer synthesis prompts plus structured cross-role outputs
- regulatory quantification: modeled under scenarios and valuation sensitivities
- non-consensus insight: explicit `variant_perception` output

## Known Conflict Hotspots

- `tradingagents/graph/setup.py`
- `tradingagents/graph/trading_graph.py`
- `tradingagents/default_config.py`
- `cli/main.py`
- `cli/utils.py`
- `tradingagents/agents/utils/agent_states.py`
- `tradingagents/agents/utils/agent_utils.py`
- reporting and final-output rendering paths

## Conflict Resolution Rules

- Prefer current `main` architecture as the baseline
- Salvage upstream behavior, not exact file diffs
- Normalize all final outputs onto one structured schema
- Keep Polymarket parallel where product boundaries differ
- Preserve backward compatibility where practical, but favor correctness over perfect prompt compatibility

## Validation Requirements

Each phase must leave the branch runnable and testable.

Minimum validation per phase:

- targeted unit tests for new modules and graph wiring
- `python -m compileall tradingagents tests`
- CLI smoke checks where relevant
- end-to-end stock analysis smoke check after stock phases
- end-to-end Polymarket smoke check after Polymarket phase

## Deliverables

- isolated branch family in `.worktrees/`
- implementation plan document
- integrated branches pushed to `guanghan`
- final integration branch that combines stock upgrades, Polymarket, and chief-analyst output standardization