docs: add docs with planning subdirectory for TODO features

docs/SNN Order Flow_Noteworthy_Conditions.txt

@@ -0,0 +1,81 @@
+Order Flow → Future Price Action: The Causal MechanismsOrder flow predicts future price action because it reveals participant intentions and liquidity structure that constrain what's economically possible.1. Imbalance Momentum: "Energy in Motion"Economic Logic:Persistent buying imbalance → Sellers getting overwhelmed → Price must rise to attract new sellers
+Persistent selling imbalance → Buyers getting overwhelmed → Price must fall to attract new buyersOrder Flow Signals:# Cumulative Volume Delta (CVD) trending
+if buy_volume - sell_volume > threshold for N consecutive periods:
+    return "MOMENTUM_BUILDING" # Price will follow the imbalance
+
+# Acceleration in imbalance  
+if current_imbalance > 2 * previous_imbalance:
+    return "MOMENTUM_ACCELERATING" # Expect larger movesFuture Price Action:Persistent imbalance → Trend continuation until exhaustionAccelerating imbalance → Parabolic moves incomingImbalance reversal → Trend change or consolidation2. Absorption Exhaustion: "The Dam Breaks"Economic Logic:Large seller absorbing buying pressure → Eventually runs out of inventory or patience
+Large buyer absorbing selling pressure → Eventually filled or steps away
+When absorption ends → Pent-up pressure explodes in breakout movesOrder Flow Signals:# High volume, flat price = absorption in progress
+if volume > 90th_percentile and price_range < 20th_percentile:
+    absorption_strength = volume * time_duration
+    
+    # Stronger absorption = bigger eventual move
+    if absorption_strength > HIGH_THRESHOLD:
+        return "EXPLOSIVE_BREAKOUT_PENDING"Future Price Action:Absorption at resistance → Breakout higher when seller exhaustedAbsorption at support → Breakdown lower when buyer exhaustedLonger absorption → Bigger eventual move (more pent-up energy)3. Volume Profile: "Fair Value Discovery"Economic Logic:High volume areas = Price levels where most participants agree on value
+Low volume areas = Price levels with disagreement or lack of interest
+Price tends to return to high-volume areas (value areas)
+Price moves quickly through low-volume areas (vacuum zones)Order Flow Signals:# Point of Control (POC) - highest volume price level
+current_price_distance_from_POC = abs(current_price - volume_POC)
+
+if current_price_distance_from_POC > 2 * average_distance:
+    return "REVERSION_TO_VALUE_LIKELY" # Price wants to return to POC
+
+# Volume gaps (vacuum zones)
+if volume_between(current_price, target_price) < LOW_THRESHOLD:
+    return "FAST_MOVE_TO_TARGET" # Price will gap quickly through thin areaFuture Price Action:Away from value → Magnetic pull back to high-volume areasNear vacuum zone → Rapid price movement through thin areasBuilding volume at new level → New value area being established4. Liquidity Mapping: "Stop Hunt Mechanics"Economic Logic:Stop losses cluster below support and above resistance
+Large players know where stops are → Incentive to trigger them for liquidity
+Stop cascades create temporary imbalances → Predictable reversal patternsOrder Flow Signals:# Stop cluster identification
+stop_density_below_support = estimate_stop_concentration(support_level)
+stop_density_above_resistance = estimate_stop_concentration(resistance_level)
+
+# When price approaches stop clusters
+if price_near_stop_cluster and volume_increasing:
+    return "STOP_HUNT_IN_PROGRESS" # Expect spike then reversal
+
+# After stops triggered
+if rapid_price_spike and volume_spike and immediate_reversal:
+    return "STOPS_CLEARED_REVERSAL_COMING"Future Price Action:Approaching stop clusters → Likely spike to trigger stops, then reversalStops recently cleared → Clean breakout more likely (obstacles removed)Multiple stop levels → Stair-step price action as each level gets cleared5. Institutional Footprints: "Smart Money Tracking"Economic Logic:Institutions move large size → Must trade patiently to avoid market impact
+Retail trades emotionally → Creates predictable patterns institutions exploit
+Institutional accumulation/distribution → Forecasts longer-term directionOrder Flow Signals:# Iceberg order detection
+if repeated_large_orders_at_same_price and price_holding_steady:
+    return "INSTITUTIONAL_ACCUMULATION" # Smart money building position
+
+# Stealth selling/buying
+if price_drifting_lower and volume_normal and no_obvious_selling:
+    return "STEALTH_DISTRIBUTION" # Institutions quietly exiting
+
+# Volume signature analysis
+if large_trades_percentage > institutional_threshold:
+    return "INSTITUTIONAL_ACTIVITY" # Smart money movingFuture Price Action:Institutional accumulation → Bullish bias over medium termInstitutional distribution → Bearish bias over medium termRetail capitulation → Contrarian opportunity (institutions step in)6. Order Flow Divergences: "Hidden Strength/Weakness"Economic Logic:Price making new highs but buying volume declining → Weak rally, expect reversal
+Price making new lows but selling volume declining → Weak selloff, expect bounceOrder Flow Signals:# Bullish divergence
+if price_making_lower_lows and buying_volume_increasing:
+    return "BULLISH_DIVERGENCE" # Bottom forming
+
+# Bearish divergence  
+if price_making_higher_highs and selling_volume_increasing:
+    return "BEARISH_DIVERGENCE" # Top forming
+
+# Volume confirmation
+if price_breakout and volume_expansion:
+    return "CONFIRMED_BREAKOUT" # Move likely to continueFuture Price Action:Volume divergence → Trend weakness, expect reversalVolume confirmation → Trend strength, expect continuationVolume exhaustion → Trend pause or reversal likelyMapping to SNN ArchitectureEnhanced 5-Neuron Model:Asset_BTC_Up: frequency = f(buying_pressure, price_impact)
+Asset_BTC_Down: frequency = f(selling_pressure, price_impact)
+Asset_BTC_Velocity: frequency = f(trade_frequency)
+Asset_BTC_Depth: frequency = f(available_liquidity)
+Asset_BTC_Imbalance: frequency = f(cumulative_volume_delta)Pattern Detection:def predict_future_action(up_freq, down_freq, velocity_freq, depth_freq, imbalance_freq):
+    # Momentum building
+    if imbalance_freq > HIGH and velocity_freq > MEDIUM:
+        return "TREND_ACCELERATION_COMING"
+    
+    # Absorption exhaustion
+    elif velocity_freq > EXTREME and depth_freq declining and imbalance_freq low:
+        return "BREAKOUT_IMMINENT"
+    
+    # Liquidity vacuum setup
+    elif depth_freq < LOW and velocity_freq > HIGH:
+        return "EXPLOSIVE_MOVE_NEXT"
+    
+    # Institutional accumulation
+    elif up_freq > down_freq and velocity_freq < MEDIUM and imbalance_freq > MEDIUM:
+        return "SMART_MONEY_BUILDING"Time Horizons for PredictionsImmediate (seconds to minutes):Imbalance momentumStop hunt mechanicsVacuum movesShort-term (minutes to hours):Absorption exhaustionVolume profile reversionBreakout confirmationMedium-term (hours to days):Institutional footprintsValue area migrationTrend divergencesKey Insight: Order flow doesn't predict exact prices, but it reveals the constraints and forces that will shape future price action. It's like reading the battlefield before the battle - you see where the armies are positioned and can predict how the fight will unfold.