track-equity-cumulative-return

<essential_principles>

All cumulative return analyses use S&P 500 (^GSPC) as the fixed benchmark. This is a core methodology decision:

• S&P 500 represents the broad US equity market
• Provides consistent, comparable baseline across all analyses
• "vs Benchmark" = Stock Return - S&P 500 Return
• Positive vs Benchmark indicates outperformance (Alpha)

This is hardcoded and cannot be changed.

For cumulative return calculation, the base date is the last trading day of the previous year:

Cumulative Return = ((Final Price / Base Price) - 1) × 100%

Key methodology:

• Analyzing 2024 → Base date is 2023-12-29 (last trading day of 2023)
• This captures the true return from year-end investment to period end

All tickers are aligned to common trading days with data.

This skill supports 4 distinct scenarios:

Scenario	Mode	Description	Example
1.a	Stock(s), Year Only	Analyze specific tickers for a single full year	NVDA, AMD in 2024 only
1.b	Stock(s), Year to Today	Analyze specific tickers from a year to today	NVDA, AMD from 2022 to today
2.a	Index Top N, Year Only	Rank index components for a single full year	Nasdaq 100 Top N in 2024 only
2.b	Index Top N, Year to Today	Rank index components from a year to today	Nasdaq 100 Top N from 2022 to today

Use --year-only flag to switch between "Year Only" (a) and "Year to Today" (b) modes.

Index Code	Name	Components
nasdaq100	Nasdaq 100 Index	~100
sp100	S&P 100 Index	100
dow30	Dow Jones 30 Index	30
sox	Philadelphia Semiconductor Index	30

Top N analysis fetches all component stocks and ranks by return.

</essential_principles>

1. Fetch Data: Get historical prices from Yahoo Finance (with caching)
2. Calculate Returns: Cumulative return
3. Benchmark Comparison: Compare against S&P 500 (fixed)
4. Rank Analysis: Index component Top N performance ranking
5. Visualization: dark theme PNG charts

Output: Cumulative return time series chart, performance ranking table, JSON data, Markdown report.

<quick_start>

Quick Start: Analyze Stock Cumulative Returns

cd skills/track-equity-cumulative-return/scripts
pip install pandas numpy yfinance matplotlib  # First time only

# Scenario 1.a: Stock(s), 2024 Year Only
python cumulative_return_analyzer.py --ticker NVDA AMD --year 2024 --year-only

# Scenario 1.b: Stock(s), 2022 to Today
python cumulative_return_analyzer.py --ticker NVDA AMD GOOGL --year 2022

# Scenario 2.a: Nasdaq 100 Top 10, 2024 Year Only
python index_component_analyzer.py --index nasdaq100 --year 2024 --year-only --top 10

# Scenario 2.b: Nasdaq 100 Top 20, 2022 to Today
python index_component_analyzer.py --index nasdaq100 --year 2022 --top 20

# Visualization (with charts)
python visualize_cumulative.py --ticker NVDA AMD --year 2024 --year-only
python visualize_cumulative.py --mode top20 --index nasdaq100 --year 2022 --top 20

Sample output:

{
  "skill": "track-equity-cumulative-return",
  "as_of": "2026-01-28",
  "mode": "year_to_today",
  "parameters": {
    "tickers": ["NVDA", "AMD"],
    "start_year": 2022,
    "year_only": false
  },
  "benchmark": {
    "ticker": "^GSPC",
    "name": "S&P 500",
    "cumulative_return_pct": 45.2
  },
  "summary": {
    "best_performer": "NVDA",
    "best_return": 542.2,
    "beat_benchmark_count": 2
  }
}