quantwise 1.2.0 → 1.2.2

package/.claude/skills/breadth-chart-analyst/references/breadth_chart_methodology.md

@@ -0,0 +1,590 @@
+# Breadth Chart Analysis Methodology
+
+This reference provides comprehensive methodology for analyzing two types of market breadth charts that provide complementary views of market health and trend status.
+
+## Overview
+
+Market breadth indicators measure the participation of stocks in market moves, providing insights into the strength and sustainability of trends that price indices alone cannot reveal. This skill focuses on two specific breadth measurements:
+
+1. **200MA-Based Breadth Index**: Medium to long-term trend assessment tool
+2. **Uptrend Stock Ratio**: Short-term trend and momentum indicator
+
+These two charts work together to provide both strategic (medium/long-term) and tactical (short-term) market perspectives.
+
+---
+
+## Chart 1: S&P 500 Breadth Index (200-Day MA Based)
+
+### Purpose and Use Case
+
+This chart measures the percentage of S&P 500 stocks trading above their 200-day moving average, providing insight into the medium to long-term health of the market. It serves as a strategic positioning tool for determining major market cycles.
+
+### Chart Components
+
+#### Primary Lines
+
+**8-Day Moving Average (8MA) - Orange Line**
+- Short-term smoothing of the breadth index
+- More responsive to rapid market changes
+- Key for identifying reversal points
+- Used as the primary signal generator for entries
+
+**200-Day Moving Average (200MA) - Green Line**
+- Long-term trend of market breadth
+- Slower to respond, filters out noise
+- Represents the underlying structural health of the market
+- Used as the primary signal generator for exits
+
+#### Reference Levels
+
+**Red Dashed Line (0.73 / 73%)**
+- **Average Peak Level**: Historical average of 200MA tops
+- **Significance**: When the breadth index exceeds this level, the market is in an overheated state
+- **Interpretation**:
+  - Above 73%: Market is extremely bullish but approaching exhaustion
+  - Significantly above 73%: Elevated risk of correction or consolidation
+  - Rarely sustainable for extended periods
+
+**Blue Dashed Line (0.23 / 23%)**
+- **Average 8MA Trough Level**: Historical average of 8MA bottoms
+- **Significance**: When the 8MA falls below this level, the market is in extreme oversold territory
+- **Interpretation**:
+  - Below 23%: Severe market stress, capitulation-level selling
+  - High probability of reversal and recovery
+  - Historically represents excellent buying opportunities
+  - Extreme fear and pessimism typically present
+
+#### Signal Markers (Triangles)
+
+**Purple/Magenta Downward Triangles (▼)**
+- **8MA Troughs**: Mark the bottoms of the 8-day moving average
+- **Significance**: Potential reversal points, especially when near or below the 23% threshold
+- **Use**: Primary buy signal when 8MA begins to turn up from a trough
+
+**Blue Downward Triangles (▼)**
+- **200MA Troughs**: Mark the bottoms of the 200-day moving average
+- **Significance**: Major market cycle lows, extremely rare
+- **Use**: Indicates the beginning of a new long-term bull market
+
+**Red Upward Triangles (▲)**
+- **200MA Peaks**: Mark the tops of the 200-day moving average
+- **Significance**: Major market cycle highs indicating trend exhaustion
+- **Use**: Primary sell signal for the tested strategy
+
+#### Background Shading
+
+**Pink Background Regions**
+- **Downtrend Periods**: Time periods when the market is in a confirmed downtrend
+- **Significance**: Higher risk environment, defensive positioning warranted
+- **Use**: Visual aid to identify unfavorable market conditions
+
+### Interpretation Framework
+
+#### Market Regimes
+
+**Healthy Bull Market**
+- 8MA and 200MA both rising
+- Breadth index between 40% and 73%
+- Regular pullbacks to 50-60% range that hold above 8MA
+- Wide participation across stocks
+
+**Overheated Bull Market**
+- Breadth index persistently above 73%
+- 8MA and 200MA both very elevated
+- High risk of near-term correction
+- Market vulnerable to negative catalysts
+
+**Market Top/Distribution Phase**
+- 200MA forming a peak (red ▲)
+- 8MA begins to roll over even if 200MA hasn't peaked yet
+- Breadth index declining from elevated levels
+- Signal to exit long positions
+
+**Bear Market/Correction**
+- Both 8MA and 200MA declining
+- Pink background shading present
+- Breadth index below 50%
+- High volatility typical
+
+**Capitulation/Extreme Oversold**
+- 8MA below 23% (blue dashed line)
+- 8MA forming a trough (purple ▼)
+- Maximum pessimism and fear
+- Historically excellent buying opportunities
+
+**Early Recovery**
+- 8MA turning up from a trough
+- 200MA may still be declining (lagging)
+- Breadth index beginning to rise from extreme lows
+- Initial phase of new uptrend
+
+### Backtested Strategy
+
+Based on historical analysis, the following strategy has demonstrated strong performance:
+
+#### Entry Rules
+
+**BUY Signal**: 8MA Trough Reversal
+- Wait for 8MA to form a clear bottom (purple ▼)
+- Especially strong when 8MA trough is below 23% (extreme oversold)
+- Enter long position in S&P 500 index when 8MA begins to turn upward
+- Confirmation: 8MA crosses above previous recent high or shows 2-3 consecutive days of increase
+
+#### Detailed Reversal Confirmation Criteria
+
+**CRITICAL**: Do not enter prematurely. A trough formation alone is NOT sufficient for entry. The reversal must be CONFIRMED.
+
+**Required Steps for Confirmation**:
+
+1. **Trough Identification** (Step 1):
+   - 8MA forms a clear bottom marked by purple ▼ triangle
+   - Trough level should ideally be below 40%, preferably below 30%
+   - Extreme troughs below 23% provide highest probability setups
+
+2. **Initial Reversal** (Step 2):
+   - 8MA begins to move upward from the trough
+   - First 1-2 periods of increase observed
+   - **WARNING**: This is NOT yet a confirmed signal - DO NOT ENTER
+
+3. **Confirmation Period** (Step 3 - MANDATORY):
+   - 8MA continues to rise for 2-3 CONSECUTIVE periods after the trough
+   - Each period should show clear upward progress (at least 2-5% increase)
+   - No significant pullbacks or reversals during confirmation period
+
+4. **Latest Data Verification** (Step 4 - CRITICAL):
+   - Analyze the RIGHTMOST 3-5 data points on the chart
+   - Verify that the 8MA is CURRENTLY rising (at the latest edge of the chart)
+   - Confirm no rollover or downward turn has occurred recently
+   - This step prevents entry on failed reversals
+
+5. **Resistance Breakout** (Step 5 - Optional but Ideal):
+   - 8MA crosses above 55-60% level
+   - This confirms strong breadth improvement
+   - Provides higher confidence in sustainability
+
+**Confirmation Status Classification**:
+
+- **CONFIRMED (Green Light)**: Steps 1-4 complete, 8MA rising for 2-3+ consecutive periods and CURRENTLY rising → ENTER
+- **DEVELOPING (Yellow Light)**: Steps 1-2 complete, but < 2 consecutive increases → WAIT, MONITOR CLOSELY
+- **FAILED (Red Light)**: Steps 1-2 occurred, but 8MA has rolled over and is declining → DO NOT ENTER, signal invalidated
+- **NO SIGNAL (Red Light)**: No trough formed → WAIT
+
+**Time-Based Confirmation**:
+- Typical confirmation period: 2-4 weeks after trough
+- If confirmation takes > 6 weeks, signal strength decreases
+- If 8MA fails to reach 55% within 6 weeks of trough, reassess validity
+
+#### Failed Reversal Patterns (WARNING SIGNS)
+
+**What is a Failed Reversal?**
+
+A failed reversal occurs when the 8MA forms a trough and begins to rise, but then rolls over and declines again before reaching sustained momentum. This invalidates the buy signal and often leads to deeper corrections.
+
+**Identifying Failed Reversals**:
+
+1. **Weak Bounce Pattern**:
+   - 8MA rises for only 1-2 periods after trough
+   - 8MA fails to reach 50-55% level
+   - 8MA then turns downward again
+   - **Result**: False signal, do NOT enter
+
+2. **Premature Rollover**:
+   - 8MA rises to 50-60% range
+   - 8MA fails to sustain the rise, begins declining
+   - 8MA shows consistent downward trajectory at latest data points
+   - **Result**: Reversal failed, exit if already entered or do not enter
+
+3. **Double Bottom Formation**:
+   - First trough forms, 8MA rises briefly
+   - 8MA declines to form second, lower trough
+   - **Result**: First trough was not the final bottom, wait for second trough to confirm
+
+**Failed Reversal Action Protocol**:
+- Immediately classify signal as INVALID
+- Do NOT enter position
+- Wait for 8MA to form a NEW, LOWER trough (often below 23%)
+- Reset analysis and wait for fresh confirmation from the new trough
+
+**Historical Failed Reversal Examples** (refer to chart):
+- Failed reversals are less common but occur during severe corrections
+- They typically precede deeper declines to extreme oversold (<23%)
+- After failed reversal, the eventual confirmed reversal from lower levels often provides excellent entries
+
+#### Latest Data Point Analysis Protocol
+
+**Why Latest Data Points Matter Most**:
+
+The most recent 3-5 data points on the chart (rightmost edge) represent the CURRENT market condition. Historical movement is context, but the latest trajectory determines whether a signal is active, developing, or failed.
+
+**Protocol**:
+
+1. **Always Start with the Rightmost Data Point**:
+   - This is the absolute latest reading
+   - This determines the CURRENT slope of the 8MA
+
+2. **Trace Backward 3-5 Data Points**:
+   - Compare current level to 1 week ago
+   - Compare current level to 2 weeks ago
+   - Compare current level to 3 weeks ago
+   - Determine if the trend is: Rising, Falling, or Flat
+
+3. **Calculate Consecutive Periods**:
+   - Count how many consecutive periods 8MA has risen
+   - Count how many consecutive periods 8MA has fallen
+   - **Confirmation requires 2-3 consecutive UP periods**
+   - **1-2 consecutive DOWN periods after a trough = failed reversal warning**
+
+4. **Visual Slope Assessment**:
+   - Visually trace the 8MA line at the rightmost edge
+   - Is the line sloping UP, DOWN, or FLAT?
+   - Do NOT rely on earlier parts of the chart - focus on the edge
+
+**Example Analysis**:
+
+```
+Scenario: 8MA formed trough at 30% three weeks ago
+
+Week-by-Week Analysis (from trough to present):
+- Week 1 after trough: 30% → 40% (UP 10%)
+- Week 2 after trough: 40% → 52% (UP 12%)
+- Week 3 after trough: 52% → 48% (DOWN 4%)
+
+Current Slope: FALLING
+Consecutive Increases: 0 (last period was DOWN)
+Status: FAILED REVERSAL - 8MA rolled over after initial bounce
+
+Action: DO NOT ENTER. Signal is invalid. Wait for new trough formation.
+```
+
+```
+Scenario: 8MA formed trough at 25% four weeks ago
+
+Week-by-Week Analysis (from trough to present):
+- Week 1 after trough: 25% → 35% (UP 10%)
+- Week 2 after trough: 35% → 45% (UP 10%)
+- Week 3 after trough: 45% → 55% (UP 10%)
+- Week 4 after trough: 55% → 60% (UP 5%)
+
+Current Slope: RISING
+Consecutive Increases: 4 (all periods UP)
+Status: CONFIRMED - Strong sustained reversal
+
+Action: ENTER LONG. Signal is confirmed and robust.
+```
+
+#### Exit Rules
+
+**SELL Signal**: 200MA Peak Detection
+- Exit long position when 200MA forms a peak (red ▲)
+- 200MA peaks typically occur when breadth index is near or above 73%
+- Do not wait for 200MA to turn down; exit at or near the peak
+- This signals the end of the bull market phase
+
+#### Risk Management
+
+- **Stop Loss**: Consider exiting if 8MA breaks decisively below its most recent trough
+- **Partial Profits**: Consider taking partial profits when breadth index exceeds 73% (overheated)
+- **Re-entry**: Do not re-enter during the same cycle unless a new 8MA trough forms
+
+#### Strategy Performance Characteristics
+
+- **Win Rate**: Historically high due to buying extreme oversold and selling into strength
+- **Hold Period**: Typically several months to over a year
+- **Drawdown Management**: Strategy avoids holding through major bear markets
+- **False Signals**: Rare due to the significant smoothing of the indicators
+
+### Analysis Checklist
+
+When analyzing this chart, systematically evaluate:
+
+1. ✓ **Current 8MA Level**: Where is the 8MA relative to historical troughs and the 23% threshold?
+2. ✓ **Current 200MA Level**: Where is the 200MA relative to historical peaks and the 73% threshold?
+3. ✓ **8MA Slope**: Is the 8MA rising, falling, or flat?
+4. ✓ **200MA Slope**: Is the 200MA rising, falling, or flat?
+5. ✓ **Recent Signal Markers**: Any recent triangles indicating troughs or peaks?
+6. ✓ **Market Regime**: Which regime best describes the current state?
+7. ✓ **Strategy Position**: Based on the backtested strategy, should one be long, flat, or preparing to enter/exit?
+8. ✓ **Distance from Thresholds**: How close is the breadth index to key levels (23%, 73%)?
+
+---
+
+## Chart 2: US Stock Market - Uptrend Stock Ratio
+
+### Purpose and Use Case
+
+This chart measures the percentage of stocks in confirmed uptrends across the US stock market, providing a real-time view of market momentum and participation. It serves as a tactical tool for short-term swing trading and confirming the strength of market moves.
+
+### Definition of "Uptrend Stock"
+
+A stock is classified as being in an uptrend when it meets ALL of the following criteria:
+
+1. **Price above 200-day MA**: Stock is in a long-term uptrend
+2. **Price above 50-day MA**: Stock is in an intermediate-term uptrend
+3. **Price above 20-day MA**: Stock is in a short-term uptrend
+4. **Positive 1-month performance**: Stock has gained value over the past month
+
+This multi-factor definition ensures that only stocks with confirmed momentum across multiple timeframes are counted as "uptrend stocks."
+
+### Chart Components
+
+#### Primary Visualization
+
+**Color-Coded Trend Identification**
+
+**Green Regions**
+- Represent periods when the market is in an **uptrend**
+- Uptrend stock ratio is generally rising
+- Positive market momentum
+- Favorable environment for long positions
+
+**Red Regions**
+- Represent periods when the market is in a **downtrend**
+- Uptrend stock ratio is generally falling
+- Negative market momentum
+- Unfavorable for long positions, defensive posture appropriate
+
+**Color Transitions**
+- **Red-to-Green Transition**: Downtrend ending, uptrend beginning (BUY signal)
+- **Green-to-Red Transition**: Uptrend ending, downtrend beginning (SELL signal)
+
+#### Reference Levels
+
+**Lower Orange Dashed Line (~10%)**
+- **Short-Term Market Bottom**: When the uptrend ratio falls to approximately 10%
+- **Significance**: Extreme oversold condition
+- **Interpretation**:
+  - Below 10%: Maximum bearish sentiment, capitulation phase
+  - High probability of near-term reversal
+  - Short-term bottom often forms at this level
+  - Excellent risk/reward for initiating long positions
+
+**Upper Orange Dashed Line (~37-40%)**
+- **Short-Term Market Top**: When the uptrend ratio approaches approximately 40%
+- **Significance**: Overbought condition, market overheating
+- **Interpretation**:
+  - Near 40%: Market is short-term overbought
+  - High probability of pullback or consolidation
+  - Reversal often begins at this level
+  - Consider taking profits or tightening stops on long positions
+
+### Interpretation Framework
+
+#### Market Conditions
+
+**Extreme Oversold (Ratio < 10%)**
+- Very few stocks participating in uptrend
+- Market-wide selling pressure
+- High fear and pessimism
+- Contrarian buying opportunity
+- Often coincides with VIX spikes
+- Watch for red-to-green transition
+
+**Moderate Bearish (Ratio 10-20%)**
+- Below-average market participation
+- Downtrend still in effect (red)
+- Selective stock strength only
+- Wait for confirmation before entering
+
+**Neutral/Transitional (Ratio 20-30%)**
+- Average market participation
+- Can be either early uptrend or late downtrend
+- Color (green vs red) is critical for context
+- Watch for trend changes
+
+**Moderate Bullish (Ratio 30-37%)**
+- Healthy uptrend participation
+- Green color dominant
+- Sustainable momentum
+- Favorable for long positions
+
+**Extreme Overbought (Ratio > 37-40%)**
+- Very high participation in uptrend
+- Market short-term overheated
+- Vulnerable to pullback
+- Watch for green-to-red transition
+- Consider profit-taking
+
+#### Trend Transitions
+
+**Red-to-Green (Downtrend to Uptrend)**
+- **Entry Signal**: Marks the beginning of a new uptrend phase
+- **Characteristics**:
+  - Uptrend ratio bottoms and begins to rise
+  - Often occurs from extreme oversold levels (<10-15%)
+  - Increasing number of stocks breaking above MAs
+  - Momentum shifting from bearish to bullish
+- **Action**: Initiate long positions in index or strong individual stocks
+
+**Green-to-Red (Uptrend to Downtrend)**
+- **Exit Signal**: Marks the end of an uptrend phase
+- **Characteristics**:
+  - Uptrend ratio peaks and begins to fall
+  - Often occurs from overbought levels (>35-40%)
+  - Stocks breaking below key moving averages
+  - Momentum shifting from bullish to bearish
+- **Action**: Exit long positions, move to cash or defensive positions
+
+### Trading Strategy
+
+#### Short-Term Swing Trading Strategy
+
+**Entry Rules**
+
+1. **Wait for Oversold Condition**:
+   - Uptrend ratio declines to 10-15% range
+   - Market in red (downtrend) phase
+
+2. **Identify Trend Reversal**:
+   - Color changes from red to green
+   - Uptrend ratio begins to rise from lows
+   - Confirmation: 2-3 consecutive increases in the ratio
+
+3. **Enter Long Position**:
+   - Buy S&P 500 index (SPY, ES futures) or basket of leading stocks
+   - Position size based on risk tolerance
+
+**Exit Rules**
+
+1. **Watch for Overbought Condition**:
+   - Uptrend ratio approaches 37-40% level
+   - Market has been green for extended period
+
+2. **Identify Trend Exhaustion**:
+   - Color changes from green to red
+   - Uptrend ratio begins to fall from highs
+   - Momentum waning
+
+3. **Exit Long Position**:
+   - Sell index position
+   - Move to cash or defensive assets
+
+**Risk Management**
+
+- **Stop Loss**: Exit if uptrend ratio breaks below recent lows while still in supposed uptrend
+- **Partial Exits**: Consider scaling out as ratio approaches 35-37%
+- **Position Sizing**: Larger positions when entering from extreme oversold (<10%), smaller when entering from moderate levels
+- **False Signals**: Quick reversals (red-green-red or green-red-green within days) may be false; wait for confirmation
+
+#### Strategy Performance Characteristics
+
+- **Timeframe**: Days to weeks (swing trading)
+- **Win Rate**: Moderate to high, depending on confirmation criteria
+- **Hold Period**: Typically 1-4 weeks
+- **Best Performance**: When entries align with extreme oversold conditions (<10%)
+- **Risk**: Whipsaws during choppy, trendless markets
+
+### Combining Both Charts
+
+For optimal decision-making, use both breadth charts together:
+
+#### Strategic Positioning (Chart 1: 200MA Breadth)
+
+- Determines overall market regime (bull, bear, neutral)
+- Guides strategic asset allocation
+- Identifies major entry/exit points for core positions
+- Longer holding periods (months to year+)
+
+#### Tactical Positioning (Chart 2: Uptrend Ratio)
+
+- Determines short-term momentum and timing
+- Guides tactical trades and position sizing
+- Identifies short-term entry/exit points for swing trades
+- Shorter holding periods (days to weeks)
+
+#### Alignment Scenarios
+
+**Scenario 1: Both Bullish**
+- Chart 1: 8MA rising, 200MA rising or flat, breadth < 73%
+- Chart 2: Green (uptrend), ratio rising from oversold
+- **Action**: Maximum bullish stance, aggressive long positioning
+
+**Scenario 2: Strategic Bullish, Tactical Bearish**
+- Chart 1: 8MA rising, 200MA not yet peaked
+- Chart 2: Red (downtrend), ratio elevated or falling
+- **Action**: Hold core long positions, avoid new tactical longs, wait for oversold
+
+**Scenario 3: Strategic Bearish, Tactical Bullish**
+- Chart 1: 200MA peaked or declining
+- Chart 2: Green (uptrend), ratio rising from extreme oversold
+- **Action**: Short-term tactical longs only, tight stops, prepare for strategic exit
+
+**Scenario 4: Both Bearish**
+- Chart 1: Both MAs declining, pink background
+- Chart 2: Red (downtrend), ratio falling
+- **Action**: Defensive positioning, cash or short positions, wait for 8MA trough
+
+### Analysis Checklist for Chart 2
+
+When analyzing the uptrend stock ratio chart, systematically evaluate:
+
+1. ✓ **Current Ratio Level**: What is the current uptrend stock percentage?
+2. ✓ **Current Color**: Is the market in green (uptrend) or red (downtrend)?
+3. ✓ **Proximity to Thresholds**: How close is the ratio to 10% (bottom) or 40% (top)?
+4. ✓ **Trend Direction**: Is the ratio rising, falling, or flat?
+5. ✓ **Recent Transitions**: Any recent color changes from red-to-green or green-to-red?
+6. ✓ **Duration of Current Trend**: How long has the current color phase lasted?
+7. ✓ **Strategy Position**: Based on the swing trading strategy, should one be long, flat, or preparing to enter/exit?
+8. ✓ **Historical Context**: How does the current reading compare to recent extremes?
+
+---
+
+## Output Requirements
+
+### Language and Style
+
+- **Analysis Language**: Conduct all thinking and analysis in English
+- **Output Format**: Generate all reports in English using markdown format
+- **Tone**: Professional, objective, analytical
+- **Terminology**: Use precise technical terms consistently
+
+### Analysis Structure
+
+Each breadth chart analysis report should include:
+
+1. **Current Readings**: Specific values for all key metrics
+2. **Signal Status**: Clear identification of any active signals (troughs, peaks, transitions)
+3. **Market Regime Assessment**: Classification of the current market environment
+4. **Strategy Implications**: Specific positioning recommendations based on the backtested strategies
+5. **Key Levels to Watch**: Upcoming thresholds or levels that would change the analysis
+6. **Risk Considerations**: Potential invalidation scenarios or alternative interpretations
+7. **Combined Analysis** (when both charts analyzed): Integration of strategic and tactical perspectives
+
+### Objectivity Standards
+
+- Base all analysis strictly on observable chart data
+- Avoid incorporating external information (news, fundamentals) unless specifically relevant to breadth interpretation
+- Clearly distinguish between factual observations and probabilistic forecasts
+- Acknowledge uncertainty when signals are ambiguous
+- Present both bullish and bearish scenarios when appropriate
+
+---
+
+## Common Pitfalls to Avoid
+
+### Chart 1 (200MA Breadth) Pitfalls
+
+- **Misreading Recent Trend Direction** (MOST COMMON ERROR): Analyzing historical chart movement instead of focusing on the LATEST 3-5 data points at the rightmost edge. This leads to stating "8MA is rising" when it's actually falling at the current edge, or vice versa. ALWAYS analyze the rightmost data points to determine CURRENT slope.
+
+- **Premature Entry**: Buying before clear 8MA reversal is confirmed (2-3 consecutive periods of increase). Entering on just a trough formation without confirmation often results in losses from failed reversals.
+
+- **Ignoring Failed Reversals**: Not recognizing when an 8MA has rolled over after an initial bounce from a trough. If the 8MA rises briefly then turns down again, the signal is INVALID.
+
+- **Late Exit**: Waiting for 200MA to decline instead of exiting at the peak formation. The peak itself is the sell signal - do not wait for confirmation of decline.
+
+- **Ignoring Thresholds**: Not recognizing significance of 23% and 73% levels. These thresholds provide critical context for entry and exit timing.
+
+- **Overtrading**: Trying to trade every wiggle in the 8MA instead of waiting for clear, confirmed trough reversals. Patience is essential for this strategy.
+
+### Chart 2 (Uptrend Ratio) Pitfalls
+
+- **Chasing**: Entering after the ratio has already risen substantially from oversold
+- **Ignoring Color**: Focusing only on the ratio level without considering trend direction (color)
+- **False Breakouts**: Not waiting for confirmation of color transitions
+- **Missing Extremes**: Not recognizing when the ratio reaches <10% or >40%
+
+### General Pitfalls
+
+- **Analyzing in Isolation**: Using only one chart without considering the other
+- **Over-Complicating**: Adding too many additional indicators that cloud the core signals
+- **Recency Bias**: Giving too much weight to the most recent move
+- **Ignoring Historical Context**: Not comparing current readings to historical patterns shown on the charts