Output Directory Structure

Last reorganized: December 11, 2025

Overview

This directory contains all outputs from the trading analysis system, organized into a structured hierarchy for easy navigation and maintenance.

Directory Layout

output/
├── analysis/          - Analysis and screening results
│   ├── screening/     - Stock screening results
│   ├── quantitative/  - Quantitative factor analysis
│   ├── technical/     - Technical analysis
│   └── red-flags/     - Red flag risk analysis
│
├── research/          - Stock research and analysis
│   └── stocks/        - One folder per ticker
│       ├── AAPL/      - All AAPL-related files
│       ├── PLTR/      - All PLTR-related files
│       └── ...        - 50+ ticker folders
│
├── market-data/       - Market data and snapshots
│   ├── snapshots/     - Market snapshots by month
│   │   ├── 2025-10/
│   │   ├── 2025-11/
│   │   └── 2025-12/
│   ├── finnhub/       - Raw Finnhub API data
│   └── yfinance/      - Raw yFinance data
│
├── strategies/        - Trading strategies
│   ├── momentum/      - Momentum desk playbooks
│   │   └── 2025-12/
│   ├── aggressive/    - Aggressive strategies
│   │   └── 2025-12/
│   ├── ultra-aggressive/ - Ultra-aggressive strategies
│   │   └── 2025-12/
│   ├── value/         - Value investing plans
│   └── weekly/        - Weekly strategy documents
│
├── portfolios/        - Portfolio data
│   ├── snapshots/     - Portfolio snapshots by month
│   │   └── 2025-12/
│   ├── allocations/   - Allocation models
│   └── recommendations/ - Portfolio recommendations
│
├── trading-desk/      - Trading desk decisions
│   ├── final-decisions/
│   └── executive-summaries/
│
├── reports/           - Custom reports
└── archive/           - Archived files

File Organization

Analysis Files

Location: analysis/

• screening/ - Screening results and candidate lists

  • screening_results.csv - Main screening output
  • final_shortlist.csv - Filtered candidates
  • screen-results-*.md - Screening reports with dates

• quantitative/ - Quantitative factor analysis and scoring

  • quantitative_analysis.json - Factor scores
  • quant_factor_scores.json - Individual factor metrics
  • Comprehensive quantitative reports

• technical/ - Technical analysis results

  • technical_analysis.json - Technical indicators (RSI, MACD, etc.)
  • Support/resistance levels, trend analysis

• red-flags/ - Risk analysis and catalyst tracking

  • red_flag_analysis.json - Risk flags for each ticker
  • catalyst_analysis.csv - Upcoming catalysts and events

Stock Research

Location: research/stocks/<TICKER>/

Each ticker has its own folder containing all related files:

• Research reports ({ticker}_research*.md, {ticker}_research*.json)
• Bull cases ({ticker}_bull_case.md)
• Bear cases ({ticker}_bear_case.md)
• Fundamental analysis ({ticker}_fundamental.md, Graham analysis)
• Sentiment analysis ({ticker}_sentiment.md)
• Data summaries ({ticker}_data_summary.md)

Example: All Palantir files are in research/stocks/PLTR/

Market Data

Location: market-data/

• snapshots/YYYY-MM/ - Monthly market snapshots

  • market_snapshot_20251211_073658.json
  • Contains: SPY price, VIX level, EUR/USD rate, volatility context

• finnhub/ - Raw Finnhub API data

  • {ticker}_finnhub_data.json - Company profiles, metrics
  • all_finnhub_data.json - Aggregated data

• yfinance/ - Raw yFinance data

  • {ticker}_yfinance_data.json - Historical prices, fundamentals
  • all_yfinance_data.json - Aggregated data

Strategies

Location: strategies/<type>/YYYY-MM/

• momentum/ - Momentum trading desk playbooks

  • Format: {date}-momentum-desk-{team-name}.md
  • Example: 20251210-momentum-desk-lunar-penguins.md

• aggressive/ - Aggressive trading strategies

  • Format: {date}-aggressive-{team-name}.md
  • 2-week trading windows

• ultra-aggressive/ - Ultra-aggressive strategies

  • Format: {date}-ultra-aggressive-{team-name}.md
  • High-beta, high-reward setups

• value/ - Value investing plans

  • Graham-style screening results
  • Long-term value opportunities

• weekly/ - Weekly strategy documents

  • weekly-strategy-{date}.md

Portfolios

Location: portfolios/

• snapshots/YYYY-MM/ - Monthly portfolio snapshots

  • portfolio_snapshot_20251207_140534.json
  • Current holdings, performance, metrics

• allocations/ - Portfolio allocation models

  • quantitative_portfolio_allocation_final.md
  • quantitative_allocation_report_dec7.md
  • Position sizing recommendations

• recommendations/ - Portfolio recommendations

  • recommended_portfolio.csv - Recommended holdings
  • portfolio_recommendation_dec6_2025.json
  • portfolio_data.json - Historical portfolio data

Trading Desk

Location: trading-desk/

• final-decisions/ - Final trading decisions

  • ultra-aggressive/ - Ultra-aggressive portfolio decisions
  • stocks/{TICKER}/ - Ticker-specific trading desk analyses

• executive-summaries/ - Quick reference documents

  • EXECUTIVE_SUMMARY_ONE_PAGE.md
  • TRADE_CARD_QUICK_REFERENCE.txt
  • Quick scannable summaries

Using the New Structure

From Python Code

The PM library provides helper methods to get the correct output paths:

from pm.config import TradingConfig

config = TradingConfig.from_yaml("config.yaml")

# Get analysis directory
analysis_dir = config.output.get_analysis_dir("screening")
# Returns: output/analysis/screening/

# Get research directory for a specific ticker
research_dir = config.output.get_research_dir("AAPL")
# Returns: output/research/stocks/AAPL/

# Get market data directory with month
market_dir = config.output.get_market_data_dir("snapshots", "2025-12")
# Returns: output/market-data/snapshots/2025-12/

# Get strategy directory with month
strategy_dir = config.output.get_strategy_dir("momentum", "2025-12")
# Returns: output/strategies/momentum/2025-12/

# Get portfolio directory
portfolio_dir = config.output.get_portfolio_dir("snapshots", "2025-12")
# Returns: output/portfolios/snapshots/2025-12/

From PM CLI

The PM CLI automatically uses the new structure:

# Research - automatically creates ticker folder
uv run pm research AAPL
# Saves to: output/research/stocks/AAPL/aapl_research_20251211_123456.md

# Market snapshot - automatically organizes by month
uv run pm market
# Saves to: output/market-data/snapshots/2025-12/market_snapshot_20251211_123456.json

# Portfolio - automatically organizes by month
uv run pm portfolio AAPL NVDA 10000
# Saves to: output/portfolios/snapshots/2025-12/portfolio_snapshot_20251211_123456.json

# Screening - saves to analysis/screening/
uv run pm screen --universe tickers.txt
# Saves to: output/analysis/screening/screening_results.csv

# Quantitative analysis
uv run pm analyze --input screening_results.csv
# Saves to: output/analysis/quantitative/quantitative_analysis.json

# Technical analysis
uv run pm technical -t AAPL -t NVDA
# Saves to: output/analysis/technical/technical_analysis.json

# Red flag checks
uv run pm check -t AAPL
# Saves to: output/analysis/red-flags/red_flag_analysis.json

From Slash Commands

Slash commands reference the new paths:

/screen - Saves to output/analysis/screening/screen-results-{DATE}.md
/momentum-desk - Saves to output/strategies/momentum/{YYYY-MM}/
/weekly-analysis - Saves to output/strategies/{type}/{YYYY-MM}/

File Naming Conventions

New Files (Standardized)

• Timestamps: YYYYMMDD_HHMMSS format
• Tickers: UPPERCASE
• Dates in filenames: YYYY-MM-DD format
• Examples:
  • AAPL_research_20251211_123456.md
  • market_snapshot_20251211_073658.json
  • 2025-12-11-momentum-desk-team-name.md

Existing Files

• Preserved as-is during migration
• May have inconsistent formats (timestamps, case)
• Located in appropriate category folders

Monthly Organization

Time-series data (market snapshots, portfolio snapshots, strategies) are organized by year-month:

market-data/snapshots/
  ├── 2025-10/
  ├── 2025-11/
  └── 2025-12/
      ├── market_snapshot_20251207_165717.json
      ├── market_snapshot_20251210_203914.json
      └── market_snapshot_20251211_073658.json

This keeps folders manageable as files accumulate over time.

Migration History

December 11, 2025 - Initial Reorganization

• Migrated 369 files from flat structure to categorized hierarchy
• Created ticker-specific folders for stock research (50+ tickers)
• Added YYYY-MM subdirectories for time-series data
• Updated PM modules, slash commands, and agents to use new structure
• Migration script: scripts/migrate_output_structure.sh
• Backup: output_backup_20251211_*/

Changes Made

1. pm/config.py - Added 6 path construction methods to OutputConfig
2. pm/research.py - Automatically creates ticker subdirectories
3. pm/market.py - Organizes snapshots by year-month
4. pm/portfolio.py - Organizes snapshots by year-month
5. pm/cli.py - Updated default output paths for all commands
6. Slash commands - Updated path references
7. Agents - Updated path examples

Finding Files

By Category

# All screening results
ls -la output/analysis/screening/

# All AAPL research
ls -la output/research/stocks/AAPL/

# December 2025 market snapshots
ls -la output/market-data/snapshots/2025-12/

# December 2025 momentum strategies
ls -la output/strategies/momentum/2025-12/

By Ticker

All files for a ticker are in one place:

ls -la output/research/stocks/PLTR/

By Date

Time-series files are organized by YYYY-MM:

ls -la output/market-data/snapshots/2025-12/
ls -la output/strategies/momentum/2025-12/

Maintenance

Archiving Old Files

Consider archiving files older than 90 days:

# Move old snapshots to archive
find output/market-data/snapshots -name "*.json" -mtime +90 -exec mv {} output/archive/ \;

Compressing Old Strategies

Compress old strategy documents:

# Compress strategies older than 30 days
find output/strategies -name "*.md" -mtime +30 -exec gzip {} \;

Cleaning Up

Remove duplicate or temporary files periodically:

# Find duplicate files
fdupes -r output/

# Remove temporary files
find output/ -name "*.tmp" -delete

Troubleshooting

File Not Found

• Check if the file was moved to a category folder
• Search by ticker: find output/research/stocks/ -name "*{TICKER}*"
• Search by pattern: find output/ -name "*{pattern}*"

Old Paths in Scripts

If a script uses old paths like output/screening_results.csv, update to:

output/analysis/screening/screening_results.csv

Or use the config methods:

config.output.get_analysis_dir("screening") / "screening_results.csv"

Missing Directories

Directories are auto-created when files are saved. If manually creating:

mkdir -p output/analysis/screening
mkdir -p output/research/stocks/TICKER
mkdir -p output/market-data/snapshots/2025-12

Contact

For questions or issues with the output structure, check:

• Migration script: scripts/migrate_output_structure.sh
• Config module: pm/config.py
• Plan document: .claude/plans/velvet-launching-blanket.md