# Phase 1 Data & Filters - Complete Explanation

## 🎯 What is Phase 1?

Phase 1 adds **4 critical features** to help you identify the **best trading signals** and **filter out noise** (hedges, rolls, low-quality signals).

---

## 📊 Phase 1 Data Fields

### 1. **Signal Tier Classification** (`signal_tier`)

**What it does:** Classifies every signal into one of three tiers based on quality.

**Values:**
- **`TIER_1`** 🥇 = **Tradeable alone** (highest quality)
- **`TIER_2`** 🥈 = **Needs confirmation** (wait 10-30 minutes, might become Tier-1)
- **`IGNORE`** 🚫 = **Don't trade** (noise, hedges, or low quality)

**How it works:**
```
TIER_1 = 🟢/🔴 + 💎 + ⭐ + premium > $500K + direction aligned
TIER_2 = 🟢 + 💎 (no ⭐) OR ⭐ without 💎
IGNORE = OTM-only, mixed signals, low volume/OI ratio
```

**Why it matters:**
- **Tier-1 signals** are institutions positioning (not hedging)
- **Tier-2 signals** often become Tier-1 later
- **Ignore signals** are likely hedges/rolls - don't waste time on them

---

### 2. **Price Reaction Tracking** (`price_reaction_5m_pct`, `flow_led_to_move`)

**What it does:** Tracks how price moves **AFTER** the signal appears.

**Fields:**
- `price_reaction_5m_pct` = Price change 5 minutes after signal (%)
- `price_reaction_15m_pct` = Price change 15 minutes after signal (%)
- `flow_led_to_move` = Boolean: Did flow lead to >0.5% price move?

**How it works:**
```
Signal appears at 10:00 AM → Price = $100
5 minutes later (10:05 AM) → Price = $101.25
price_reaction_5m_pct = +1.25%

If |price_reaction_5m_pct| > 0.5% → flow_led_to_move = true
```

**Why it matters:**
- **Flow WITH price reaction** = Real positioning (trade it!)
- **Flow WITHOUT price reaction** = Hedge or roll (ignore it!)

**Example:**
- Signal shows 🟢💎⭐ with $1M premium
- But price doesn't move → It's a hedge, not real positioning
- Filter it out!

---

### 3. **VWAP Integration** (`vwap_at_signal`, `price_vs_vwap_pct`)

**What it does:** Calculates VWAP (Volume Weighted Average Price) and shows distance from it.

**Fields:**
- `vwap_at_signal` = VWAP value at signal time
- `price_vs_vwap_pct` = Percentage distance from VWAP

**How it works:**
```
VWAP = Average price weighted by volume (from 9:30 AM to signal time)
price_vs_vwap_pct = ((Current Price - VWAP) / VWAP) * 100

Example:
- VWAP = $100
- Current Price = $101
- price_vs_vwap_pct = +1.0%
```

**Why it matters:**
- **Price near VWAP** = Good entry opportunity
- **Price far from VWAP** (>2%) = Wait for pullback
- **VWAP pullback/reclaim** = Best entry strategy

**Trading Logic:**
- ✅ **Best entry:** VWAP pullback or VWAP reclaim
- ✅ **Good entry:** Break & hold above prior high
- ❌ **Avoid:** Chasing vertical candles (price too extended)

---

### 4. **Trade Checklist** (`checklist_score`, `checklist_passed`)

**What it does:** Evaluates signals against a 5-point checklist. Requires 4/5 to pass.

**Checklist Items:**
1. ✅ Has direction (🟢 or 🔴)
2. ✅ Has diamond (💎)
3. ✅ Has star (⭐)
4. ✅ Price respects VWAP (within ±2%)
5. ✅ Index confirms (SPY/QQQ alignment - placeholder for Phase 2)

**Fields:**
- `checklist_score` = Score out of 5 (0-5)
- `checklist_passed` = Boolean: True if score >= 4
- `checklist_details` = Object showing which checks passed/failed

**How it works:**
```
Example:
✅ Has direction (🟢) = 1 point
✅ Has diamond (💎) = 1 point
✅ Has star (⭐) = 1 point
✅ Price respects VWAP = 1 point
❌ Index confirms = 0 points (not implemented yet)

Total: 4/5 → checklist_passed = true
```

**Why it matters:**
- **Prevents bad trades** - Only trade signals that pass 4/5 checks
- **Quality filter** - Ensures multiple conditions are met
- **Reduces false signals** - Filters out incomplete setups

---

## 🔍 Phase 1 Filters

### Filter 1: **🥇 Tier-1 Only**

**What it does:** Shows only Tier-1 signals (highest quality, tradeable alone).

**When to use:**
- When you want **only the best signals**
- When you're **short on time** - focus on Tier-1 only
- When you want **institutional positioning** (not hedges)

**What it filters:**
- ✅ Shows: Tier-1 signals only
- ❌ Hides: Tier-2 and Ignore signals

**Example:**
```
Without filter: 50 signals (10 Tier-1, 20 Tier-2, 20 Ignore)
With filter: 10 signals (only Tier-1)
```

---

### Filter 2: **✅ Checklist Passed**

**What it does:** Shows only signals that passed the 4/5 checklist.

**When to use:**
- When you want **validated trades** only
- When you want to **avoid incomplete setups**
- When you want **multiple confirmations**

**What it filters:**
- ✅ Shows: Signals with checklist_score >= 4
- ❌ Hides: Signals with checklist_score < 4

**Example:**
```
Without filter: 50 signals (30 passed, 20 failed)
With filter: 30 signals (only passed)
```

---

### Filter 3: **📈 Flow Led to Move**

**What it does:** Shows only signals where flow led to actual price movement (>0.5%).

**When to use:**
- When you want **real positioning** (not hedges)
- When you want to **filter out noise**
- When you want **signals that actually moved price**

**What it filters:**
- ✅ Shows: Signals where price moved >0.5% after signal
- ❌ Hides: Signals where price didn't move (likely hedges/rolls)

**Example:**
```
Without filter: 50 signals (20 moved price, 30 didn't)
With filter: 20 signals (only ones that moved price)
```

---

## 🎯 Combined Filter Strategy

### Best Signals (All 3 Filters ON):
```
🥇 Tier-1 Only + ✅ Checklist Passed + 📈 Flow Led to Move

Result: Only the highest quality signals that:
- Are Tier-1 (tradeable alone)
- Passed 4/5 checklist
- Led to actual price movement

Example: 50 signals → 5 signals (only the best!)
```

### Conservative Strategy:
```
🥇 Tier-1 Only + ✅ Checklist Passed

Result: High-quality validated signals
(Even if price hasn't moved yet - might be early)
```

### Aggressive Strategy:
```
📈 Flow Led to Move

Result: Any signal that moved price
(Includes Tier-2 if they moved price)
```

---

## 📈 Real-World Example

### Scenario: You see a signal

**Signal Details:**
- Symbol: AAPL
- Badges: 🟢💎⭐
- Premium: $750K
- Time: 10:00 AM
- Price: $150

**Phase 1 Data:**
- `signal_tier` = `TIER_1` ✅
- `checklist_score` = `4` ✅
- `checklist_passed` = `true` ✅
- `price_reaction_5m_pct` = `+1.2%` ✅
- `flow_led_to_move` = `true` ✅
- `vwap_at_signal` = `$149.50`
- `price_vs_vwap_pct` = `+0.33%` ✅

**Analysis:**
- ✅ Tier-1 signal (highest quality)
- ✅ Passed checklist (4/5)
- ✅ Flow led to price move (+1.2% in 5 minutes)
- ✅ Price near VWAP (good entry)

**Decision:** **TRADE IT!** This is a high-quality signal with multiple confirmations.

---

### Scenario: Another signal

**Signal Details:**
- Symbol: MSFT
- Badges: 🟢💎 (no ⭐)
- Premium: $200K
- Time: 11:00 AM
- Price: $300

**Phase 1 Data:**
- `signal_tier` = `TIER_2` ⚠️
- `checklist_score` = `3` ❌
- `checklist_passed` = `false` ❌
- `price_reaction_5m_pct` = `+0.1%` ❌
- `flow_led_to_move` = `false` ❌
- `vwap_at_signal` = `$299.50`
- `price_vs_vwap_pct` = `+0.17%`

**Analysis:**
- ⚠️ Tier-2 signal (needs confirmation)
- ❌ Failed checklist (3/5)
- ❌ Flow didn't lead to price move (only +0.1%)
- ✅ Price near VWAP

**Decision:** **WAIT or IGNORE** - Not enough confirmations, price didn't react.

---

## 🎯 Summary

### Phase 1 Data Helps You:
1. **Identify quality** - Tier-1 vs Tier-2 vs Ignore
2. **Filter hedges** - Flow without price reaction = hedge
3. **Find entries** - VWAP distance shows entry opportunities
4. **Validate trades** - Checklist ensures multiple conditions met

### Phase 1 Filters Help You:
1. **Focus on best signals** - Tier-1 only
2. **Avoid bad trades** - Checklist passed only
3. **Filter noise** - Flow led to move only

### The Goal:
**Trade only the highest quality signals that:**
- Are Tier-1 (institutional positioning)
- Passed checklist (multiple confirmations)
- Led to price movement (real positioning, not hedge)

**Result:** Higher win rate, fewer false signals, better entries!

---

## 💡 Pro Tips

1. **Start with all 3 filters ON** - See only the best signals
2. **If no results, turn off one filter** - Gradually relax criteria
3. **Check VWAP distance** - Best entries are near VWAP
4. **Monitor price reaction** - If flow doesn't move price, it's likely a hedge
5. **Use Tier-2 as watchlist** - They often become Tier-1 later

---

**Remember:** Phase 1 is about **quality over quantity**. Better to trade 5 great signals than 50 mediocre ones!