docs: Add comprehensive v11 indicator documentation

- Create V11_INDICATOR_GUIDE.md (complete testing and usage guide) - Create V11_QUICK_REFERENCE.md (quick reference card) - Document bug fix, filter logic, testing workflow - Include configuration presets and troubleshooting - Add performance expectations and comparison tables Co-authored-by: mindesbunister <32161838+mindesbunister@users.noreply.github.com>
2025-12-06 18:03:04 +00:00
parent fae899a1f6
commit 40fd60fa8f
2 changed files with 571 additions and 0 deletions
--- a/docs/V11_INDICATOR_GUIDE.md
+++ b/docs/V11_INDICATOR_GUIDE.md
@@ -0,0 +1,381 @@
+# v11 Indicator Guide - All Filters Functional
+
+## Overview
+The v11 indicator fixes a critical bug in v9 where filter variables were calculated but never applied to signal generation. v11 ensures all quality filters are properly enforced when enabled.
+
+## Quick Start
+
+### Loading v11 on TradingView
+1. Open TradingView chart (5-minute SOL recommended for testing)
+2. Click "Pine Editor" at bottom
+3. Copy contents of `workflows/trading/moneyline_v11_all_filters.pinescript`
+4. Click "Add to chart"
+
+### Side-by-Side Comparison with v9
+1. Load v9 on one chart instance
+2. Load v11 on duplicate chart instance
+3. Set `useQualityFilters = false` in v11
+4. Verify both show identical signals (v9 behavior)
+5. Set `useQualityFilters = true` in v11
+6. Observe v11 shows FEWER signals (only high-quality)
+
+## The Bug That Was Fixed
+
+### v9 Bug (Lines 263-264)
+```pinescript
+// V9: Calculated these filter variables:
+longOk = not useMacd or (macdLine > macdSignal)
+adxOk = not useAdx or (adxVal > adxMin)
+longBufferOk = not useEntryBuffer or (calcC > supertrend + entryBufferATR * atr)
+// ... and 7 more filter variables
+
+// But NEVER used them in final signals!
+finalLongSignal = buyReady  // ❌ Only timing check
+finalShortSignal = sellReady  // ❌ Only timing check
+```
+
+**Impact:** All the filter toggles in the UI did nothing. ADX filter enabled? Ignored. Volume filter? Ignored. Position filter? Ignored.
+
+### v11 Fix (Lines 261-272)
+```pinescript
+// V11: Master toggle to enable/disable all filters at once
+useQualityFilters = input.bool(true, "Enable ALL quality filters", ...)
+
+// V11: Apply ALL filters to final signals
+finalLongSignal = buyReady and (not useQualityFilters or (
+    longOk and 
+    adxOk and 
+    longBufferOk and 
+    longPositionOk and 
+    volumeOk and 
+    rsiLongOk
+))
+
+finalShortSignal = sellReady and (not useQualityFilters or (
+    shortOk and 
+    adxOk and 
+    shortBufferOk and 
+    shortPositionOk and 
+    volumeOk and 
+    rsiShortOk
+))
+```
+
+**Result:** All 10 filter variables are now properly enforced when their respective toggles are enabled.
+
+## Filter Variables Explained
+
+### 1. longOk / shortOk (MACD Confirmation)
+- **Controlled by:** `useMacd` toggle
+- **Logic:** MACD line must be above/below signal line for long/short
+- **Default:** Disabled (`useMacd = false`)
+- **Purpose:** Ensure momentum confirms direction
+
+### 2. adxOk (ADX Trend Strength)
+- **Controlled by:** `useAdx` toggle + `adxMin` value
+- **Logic:** ADX must be ≥ minimum value (default: 21)
+- **Default:** Enabled (`useAdx = true`, `adxMin = 21`)
+- **Purpose:** Filter out choppy/weak trends
+
+### 3. longBufferOk / shortBufferOk (Entry Buffer)
+- **Controlled by:** `useEntryBuffer` toggle + `entryBufferATR` value
+- **Logic:** Price must be beyond Money Line by buffer amount
+- **Default:** Enabled (`useEntryBuffer = true`, `entryBufferATR = 0.20`)
+- **Purpose:** Avoid wick flips, require meaningful breach
+
+### 4. longPositionOk / shortPositionOk (Price Position)
+- **Controlled by:** `usePricePosition` toggle + `longPosMax`/`shortPosMin` values
+- **Logic:** 
+  - Long: Price must be below X% of 100-bar range (default: 75%)
+  - Short: Price must be above X% of 100-bar range (default: 20%)
+- **Default:** Enabled (`usePricePosition = true`)
+- **Purpose:** Prevent chasing extremes (buying tops, shorting bottoms)
+
+### 5. volumeOk (Volume Filter)
+- **Controlled by:** `useVolumeFilter` toggle + `volMin`/`volMax` values
+- **Logic:** Volume ratio must be between min and max (default: 1.0-3.5x average)
+- **Default:** Enabled (`useVolumeFilter = true`)
+- **Purpose:** Filter dead moves (too low) and climax moves (too high)
+
+### 6. rsiLongOk / rsiShortOk (RSI Momentum)
+- **Controlled by:** `useRsiFilter` toggle + RSI range values
+- **Logic:**
+  - Long: RSI must be 35-70 (default)
+  - Short: RSI must be 30-70 (default)
+- **Default:** Enabled (`useRsiFilter = true`)
+- **Purpose:** Ensure momentum is in valid range (not oversold for longs, not overbought for shorts)
+
+## Master Toggle: useQualityFilters
+
+### Purpose
+Allows easy A/B testing between:
+- v9 behavior (timing only)
+- v11 behavior (all filters enforced)
+
+### When useQualityFilters = FALSE
+```pinescript
+finalLongSignal = buyReady and (not useQualityFilters or (...))
+                  ↓
+finalLongSignal = buyReady and TRUE  // Always true
+                  ↓
+finalLongSignal = buyReady  // Same as v9!
+```
+
+**Result:** Behaves exactly like v9 (only timing controls signals)
+
+### When useQualityFilters = TRUE
+```pinescript
+finalLongSignal = buyReady and (not useQualityFilters or (longOk and adxOk and ...))
+                  ↓
+finalLongSignal = buyReady and (false or (longOk and adxOk and ...))
+                  ↓
+finalLongSignal = buyReady and (longOk and adxOk and ...)  // All must pass!
+```
+
+**Result:** All enabled filter conditions must pass
+
+## Testing Workflow
+
+### Step 1: Verify v9 Equivalence
+```
+1. Load v11 on chart
+2. Set useQualityFilters = false
+3. Count signals over 24 hours
+4. Load v9 on duplicate chart
+5. Count signals over same 24 hours
+6. ✅ Should be IDENTICAL
+```
+
+### Step 2: Verify Filter Enforcement
+```
+1. Set useQualityFilters = true
+2. Count signals over 24 hours
+3. ✅ Should see FEWER signals than v9
+4. ✅ Reduction % depends on how many filters are enabled
+```
+
+### Step 3: Test Individual Filter Toggles
+```
+With useQualityFilters = true:
+
+Test ADX Filter:
+1. useAdx = true, adxMin = 21
+2. Count signals over 4 hours → X signals
+3. useAdx = false
+4. Count signals over 4 hours → Y signals
+5. ✅ Y should be ≥ X (more signals when filter disabled)
+
+Test Volume Filter:
+1. useVolumeFilter = true, volMin = 1.0
+2. Count signals over 4 hours → X signals
+3. useVolumeFilter = false
+4. Count signals over 4 hours → Y signals
+5. ✅ Y should be ≥ X (more signals when filter disabled)
+
+Repeat for each filter...
+```
+
+### Step 4: Test Filter Combinations
+```
+Scenario: Very Strict (All filters enabled)
+- useAdx = true, adxMin = 25 (stronger trend)
+- useEntryBuffer = true, entryBufferATR = 0.30 (larger buffer)
+- usePricePosition = true, longPosMax = 60 (avoid top 40%)
+- useVolumeFilter = true, volMin = 1.5 (stronger volume)
+- useRsiFilter = true, tight ranges
+- useMacd = true
+
+✅ Should see VERY FEW signals (only highest quality)
+
+Scenario: Moderate (Some filters enabled)
+- useAdx = true, adxMin = 18 (moderate trend)
+- useEntryBuffer = true, entryBufferATR = 0.15
+- usePricePosition = false (allow any position)
+- useVolumeFilter = false (allow any volume)
+- useRsiFilter = true, wide ranges
+- useMacd = false
+
+✅ Should see MORE signals than strict mode
+
+Scenario: Permissive (Like v9)
+- useQualityFilters = false
+
+✅ Should match v9 exactly
+```
+
+## Expected Results
+
+### Signal Frequency Comparison
+
+| Configuration | Expected Signals per Day | Quality Level |
+|--------------|-------------------------|---------------|
+| v9 (baseline) | 100% | Mixed (no filtering) |
+| v11 useQualityFilters=false | 100% | Mixed (v9 equivalent) |
+| v11 default settings | 40-60% | High (all filters at defaults) |
+| v11 strict settings | 10-20% | Very High (tighter thresholds) |
+| v11 permissive settings | 70-80% | Moderate (some filters disabled) |
+
+### Signal Quality Metrics
+
+**What to measure:**
+1. **Win Rate** - % of signals that hit TP1 before SL
+2. **Average MFE** - Maximum Favorable Excursion (best profit %)
+3. **Average MAE** - Maximum Adverse Excursion (worst drawdown %)
+4. **Profit Factor** - Total profit / Total loss
+
+**Expected improvements with useQualityFilters=true:**
+- ✅ Higher win rate (fewer bad signals filtered out)
+- ✅ Lower MAE (better entry timing from filters)
+- ✅ Higher profit factor (quality over quantity)
+- ⚠️ Fewer signals (trade-off for quality)
+
+## Alert Messages
+
+Both v9 and v11 include identical context metrics in alert messages:
+
+```
+SOL buy 5 | ATR:0.43 | ADX:26.9 | RSI:58 | VOL:1.25 | POS:45.2 | MAGAP:0.35 | IND:v11
+```
+
+**Fields:**
+- **ATR** - Average True Range as % of price
+- **ADX** - Trend strength (0-100)
+- **RSI** - Relative Strength Index (0-100)
+- **VOL** - Volume ratio vs 20-bar average
+- **POS** - Price position in 100-bar range (0-100%)
+- **MAGAP** - MA50-MA200 gap as % (positive=bullish, negative=bearish, ~0=convergence)
+- **IND** - Indicator version (v9, v11, etc.)
+
+The difference is:
+- **v9:** Sends alerts for ALL signals regardless of filter values
+- **v11 (useQualityFilters=true):** Only sends alerts for signals that pass ALL enabled filters
+
+## Configuration Recommendations
+
+### Conservative (High Quality, Low Frequency)
+```pinescript
+useQualityFilters = true
+useAdx = true, adxMin = 25
+useEntryBuffer = true, entryBufferATR = 0.30
+usePricePosition = true, longPosMax = 65, shortPosMin = 25
+useVolumeFilter = true, volMin = 1.5, volMax = 3.0
+useRsiFilter = true, rsiLongMin = 40, rsiLongMax = 65
+useMacd = true
+```
+
+### Balanced (Default v11 Settings)
+```pinescript
+useQualityFilters = true
+useAdx = true, adxMin = 21
+useEntryBuffer = true, entryBufferATR = 0.20
+usePricePosition = true, longPosMax = 75, shortPosMin = 20
+useVolumeFilter = true, volMin = 1.0, volMax = 3.5
+useRsiFilter = true, rsiLongMin = 35, rsiLongMax = 70
+useMacd = false
+```
+
+### Aggressive (More Signals, Lower Quality)
+```pinescript
+useQualityFilters = true
+useAdx = true, adxMin = 15
+useEntryBuffer = true, entryBufferATR = 0.10
+usePricePosition = false
+useVolumeFilter = false
+useRsiFilter = true, rsiLongMin = 30, rsiLongMax = 75
+useMacd = false
+```
+
+### v9 Equivalent (No Filtering)
+```pinescript
+useQualityFilters = false
+// All other filter settings ignored
+```
+
+## Troubleshooting
+
+### Issue: v11 with useQualityFilters=false doesn't match v9 signals
+
+**Diagnosis:**
+1. Check `confirmBars` setting (should be same in both)
+2. Check `flipThreshold` setting (should be same in both)
+3. Verify both using same timeframe and symbol
+
+**If still different:**
+- Verify you're using the correct v9 file (not v8 or v10)
+- Check for any manual edits to either file
+
+### Issue: v11 shows NO signals with useQualityFilters=true
+
+**Diagnosis:**
+Your filter settings are too strict. Check:
+1. `adxMin` - Try lowering (e.g., 15 instead of 25)
+2. `entryBufferATR` - Try reducing (e.g., 0.10 instead of 0.30)
+3. Individual filter toggles - Try disabling some filters
+
+**Quick fix:**
+Start with all filters disabled, then enable one at a time to identify which filter is blocking all signals.
+
+### Issue: Individual filter toggles don't seem to affect signals
+
+**Diagnosis:**
+This would indicate the same bug v9 had. Verify:
+1. You're using v11 (check indicator title on chart)
+2. `useQualityFilters = true` (if false, filters are intentionally ignored)
+3. The filter toggle is actually enabled (check settings panel)
+
+### Issue: Too many signals still (similar to v9)
+
+**Diagnosis:**
+1. Verify `useQualityFilters = true` (not false)
+2. Check which filters are enabled (some may be toggled off)
+3. Consider tightening filter thresholds:
+   - Increase `adxMin` (e.g., 21 → 25)
+   - Increase `volMin` (e.g., 1.0 → 1.5)
+   - Tighten RSI ranges
+
+## Performance Expectations
+
+Based on v9 backtesting data (Nov 2024 - Nov 2025):
+
+### v9 Baseline (No Filters)
+- **Signals:** ~500-600 per year
+- **Win Rate:** ~60%
+- **Profit Factor:** ~1.02
+- **Issue:** Many low-quality signals in chop
+
+### v11 Projected (All Filters Enabled)
+- **Signals:** ~200-300 per year (50-60% reduction)
+- **Win Rate:** ~70-75% (expected improvement)
+- **Profit Factor:** ~1.5-2.0 (expected improvement)
+- **Benefit:** Higher quality signals, less chop
+
+**Note:** Actual performance will vary based on:
+- Specific filter settings chosen
+- Market conditions (trending vs choppy)
+- Timeframe used (5min vs higher)
+- Symbol traded (SOL vs ETH vs BTC)
+
+## Next Steps
+
+1. **Load v11 on TradingView** - Test on SOL 5-minute chart
+2. **Verify v9 equivalence** - Set useQualityFilters=false, compare with v9
+3. **Test individual filters** - Enable filters one by one, observe effect
+4. **Find optimal settings** - Adjust thresholds based on your risk tolerance
+5. **Forward test** - Run for 50-100 trades, measure win rate and profit factor
+6. **Compare with v9** - Determine if v11 provides meaningful improvement
+
+## Documentation
+
+- **Source File:** `workflows/trading/moneyline_v11_all_filters.pinescript`
+- **Based On:** v9 MA Gap indicator
+- **Lines Changed:** 4 sections (metadata, master toggle, signal logic, version)
+- **Total Lines:** 300 (vs v9's 292)
+- **Git Commit:** `feat: Create v11 indicator with all filter options functional`
+
+## Questions?
+
+If you encounter issues or unexpected behavior:
+1. Check this guide's Troubleshooting section
+2. Verify you're using v11 (not v9 or v10)
+3. Compare with v9 using useQualityFilters=false (should match exactly)
+4. Review filter logic in lines 261-272 of the source file