# OPERATIONAL DOCTRINE: THE SURVIVAL-MOMENTUM PROTOCOL

**TO:** All Trading Agents, Analysts, and Portfolio Managers  
**FROM:** System Architect / Risk Control  
**DATE:** January 11, 2026  
**SUBJECT:** OPERATIONAL DOCTRINE: THE SURVIVAL-MOMENTUM PROTOCOL

---

## THE CORE MANDATE

We are not value investors. We are not momentum chasers. **We are Survivalists.**

Our goal is to **capture Alpha during paradigm shifts while guaranteeing survival during regime collapses.** We achieve this by adhering to a rigid hierarchy of logic that prioritizes **Hard Data** over Narrative and **Trend** over Opinion.

---

## I. THE HIERARCHY OF TRUTH

In the event of a conflict between agents or data sources, this hierarchy governs the decision:

1.  **Hard Code Overrides (The Safety Valves):** If `Price > 200SMA` and `Growth > 30%`, the system **CANNOT** sell, regardless of the Analyst’s fear.
2.  **Mathematical Regime (The Context):** The output of the `RegimeDetector` (Volatility + ADX) is the law. If the math says **TRENDING_UP**, the LLM cannot hallucinate "Uncertainty."
3.  **Fundamental Data (The Fuel):** Revenue Growth, FCF Margins, and Insider Activity are facts. Narratives about "future potential" are opinions.
4.  **LLM Synthesis (The Narrative):** The Analyst's prose is the last filter, not the first.

---

## II. THE MOMENTUM EXCEPTION ("Don't Fight the Tape")

Value traps look cheap; Momentum rockets look expensive. **We do not short innovation.**

### The Rule
Valuation multiples (P/E, P/S) are **irrelevant** if:
1.  The Asset is in a **Confirmed Uptrend** (Price > 200 SMA).
2.  The Asset is in **Hyper-Growth** (Revenue Growth > 30%).
3.  The Market Regime is **Bullish/Momentum**.

### The Consequence
In this state, we **HOLD**. We do not "take profits" because a stock is "too high." We only sell when the Trend breaks or the Growth slows.

---

## III. THE SURVIVAL PRIORITY ("Don't Catch Knives")

When the regime shifts to **VOLATILE** or **TRENDING_DOWN**:

1.  **Valuation Matters Instantly:** 100x P/S is a death sentence in a downtrend.
2.  **Insider Selling is a Siren:** If insiders sell into a downtrend, we exit immediately.

### The Rule
If expected value is negative and the trend is broken, we **liquidate**. We do not "average down." We do not "buy the dip" on broken structural stories.

### Sizing
In **Unknown/Volatile** regimes, position sizing must be reduced to ensure no single failure threatens the portfolio.

---

## IV. THE RELATIVE STRENGTH DOCTRINE

We judge assets not in a vacuum, but against the Tide.

*   If the Market (SPY) is Flat/Choppy and the Asset is Trending Up, this is **Alpha**. We press the advantage.
*   If the Market is Up and the Asset is Flat, this is **Weakness**. We cut the laggard.


---

## VI. THE LEARNING LOOP (Dynamic Parameter Tuning)

We do not just execute; we adapt. The system includes a **Self-Reflection Mechanism** that reviews past performance and tunes internal parameters.

1.  **Reflection:** After every decision, the `Reflector` analyzes the outcome (Returns vs. Logic).
2.  **Tuning:** If the strategy was too slow (lagging) or too fast (whipsawed), the Reflector adjusts core parameters:
    *   `rsi_period`: Lowered for faster reaction in Volatile markets.
    *   `risk_multiplier`: Capped during drawdowns.
    *   `stop_loss_pct`: Tightened if losses exceed projections.
3.  **Persistence:** These "Lessons" are saved to `runtime_config.json` and applied to **All Future Decisions**.

---

## VII. SYSTEM ARCHITECTURE (The Digital Bedrock)

### 1. The Parallel Doctrine ("Fan-Out / Fan-In")
*   **Concept:** Speed is Alpha. We do not wait for News to finish before reading Social Media.
*   **Architecture:** The `Market Analyst` triggers `Social`, `News`, and `Fundamentals` simultaneously. They run in parallel threads.
*   **Safety Protocol:** To prevent "State Contamination" (Race Conditions):
    *   **Subgraphs:** Each analyst runs in an isolated `StateGraph` sandbox. They share NO memory.
    *   **Strict Schemas:** Analysts can only read what they need (`Symbol`, `Date`) and write what they own (`Report`). They CANNOT touch the Portfolio.

### 2. The Crash-Proof Guarantee
*   **Rule:** **NO ANALYST DIES ALONE.**
*   **Implementation:** All tool nodes are wrapped in `try/except` logic. If an API fails (Rate Limit, 500 Error), the tool returns a formatted error string to the Agent. The Agent then notes the failure and proceeds. The system **never** hard-crashes on a single data point failure.

---

## V. EXECUTION DISCIPLINE

1.  **Binary Thinking is the Enemy:** Rarely is the answer "Sell 100%" or "Buy 100%." We scale out of risks and scale into strength.
2.  **No Hallucinations:** We do not invent "SG&A explosions" to justify fear. We verify data against the source.
3.  **The Stop Loss:** A Stop Loss is not a suggestion; it is a mechanism of **survival**. It must be respected above all conviction.

---

## SUMMARY

*   We are aggressive when the math supports velocity.
*   We are cowardly when the math signals destruction.
*   We do not have "feelings" about stocks. We have parameters.

**Execute.**

---

# USER MANUAL: LOGIC & RULES

This document details the operational logic of the Survival-Momentum Protocol. It translates the high-level doctrine into specific algorithmic rules, hard-coded overrides, and stress-test scenarios.

This is the "User Manual" for the machine you have built.

## 1. THE RULES (The Logic Engines)
These are the fundamental laws programmed into the `RegimeDetector` and `MarketAnalyst`.

### Rule A: The "Price is Truth" Law
*   **Concept:** Fundamental data (Earnings, P/E) is lagging (past). Price action is leading (future).
*   **The Code Logic:**
    *   **IF** `RegimeDetector` calculates **TRENDING_UP** (based on ADX > 25 + Positive Returns),
    *   **THEN** the system ignores traditional valuation warnings like "Overbought RSI" or "High P/E."
*   **Why:** In a mania, "Overbought" stays overbought for months. Selling early is a failure.

### Rule B: The "Insider Veto" Law
*   **Concept:** Insiders know more than the algorithm.
*   **The Code Logic:**
    *   **IF** Net Insider Activity is **Negative (Selling) > $50M** in the last quarter,
    *   **AND** Stock Price is **Below the 50-day SMA**,
    *   **THEN** Buy signals are **Disabled**.
*   **Why:** Smart money selling into a downtrend is the ultimate "Get Out" signal.

### Rule C: The "Relative Strength" Filter
*   **Concept:** Don't buy a boat that is sinking while the tide is rising.
*   **The Code Logic:**
    *   **IF** SPY (Broad Market) is **TRENDING_UP**,
    *   **BUT** Target Asset is **SIDEWAYS** or **TRENDING_DOWN**,
    *   **THEN** The asset is flagged as **WEAKNESS**.
*   **Action:** The Trader must prefer Leaders (Stocks matching or beating SPY regime) over Laggards.

## 2. THE OVERRIDES (The Hard Gates)
These are the Python functions in `trading_graph.py` that physically block the LLM from executing a bad decision.

### Override 1: The "Don't Fight the Tape" (The PLTR Fix)
*   **Trigger:** The Analyst LLM tries to **SELL** or **SHORT**.
*   **The Check:**
    1.  Is Price > 200-day Simple Moving Average (SMA)?
    2.  Is Revenue Growth > 30% YoY?
    3.  Is Market Regime **TRENDING_UP** or **BULL**?
*   **The Intervention:** If **ALL TRUE**, the system effectively "slaps the hand" of the Trader.
*   **Result:** Order converted from **SELL** to **HOLD**.
*   **Log Output:** `🛑 TREND OVERRIDE TRIGGERED: Cannot short hyper-growth in uptrend.`

### Override 2: The "Falling Knife" Guard (The Zoom/Peloton Fix)
*   **Trigger:** The Analyst LLM tries to **BUY** the dip.
*   **The Check:**
    1.  Is Price < 200-day SMA? (Downtrend)
    2.  Is Market Regime **VOLATILE** or **TRENDING_DOWN**?
    3.  Is Valuation > 50x P/S?
*   **The Intervention:** If **ALL TRUE**, the system blocks the Buy.
*   **Result:** Order converted from **BUY** to **WAIT**.
*   **Log Output:** `🛑 SAFETY VALVE TRIGGERED: Valuation too high for broken trend.`

## 3. SAMPLE SCENARIOS (Stress Tests)
Here is how the system handles specific market environments compared to a standard "Value" or "Momentum" bot.

### Scenario A: The "Rocket Ship" (e.g., NVIDIA in 2023 / PLTR Now)
*   **The Setup:** Stock is up 200%. P/E ratio is 150x. Everyone on CNBC says it's a bubble.
*   **The Value Investor Bot:** Sells immediately. "Overvalued."
*   **The Human Trader:** Panic sells to lock in profits, then cries as it doubles again.
*   **YOUR SYSTEM:**
    *   **Regime:** Detects **TRENDING_UP** (High Volatility is accepted via Momentum Exception).
    *   **Analyst:** Screams "Valuation Risk!"
    *   **Override:** Checks Growth > 30% + Price > 200SMA.
    *   **Decision:** **HOLD**.
    *   **Outcome:** You ride the bubble until the trend actually breaks.

### Scenario B: The "Tech Crash" (e.g., ZOOM in 2022)
*   **The Setup:** Stock was $500, now $400. P/S is still 80x. Revenue growth slows from 300% to 40%.
*   **The "Dip Buyer" Bot:** Buys. "It's cheap compared to last month!"
*   **YOUR SYSTEM:**
    *   **Regime:** Detects **TRENDING_DOWN** (Price < SMA, ADX High).
    *   **Analyst:** "Fundamentals still look okay, maybe a buy?"
    *   **Override:** Checks Price < 200SMA + Valuation (80x P/S) > Limit.
    *   **Decision:** **SELL / AVOID**.
    *   **Outcome:** You exit at $400 before it goes to $60.

### Scenario C: The "Choppy Market" (e.g., SPY in 2015)
*   **The Setup:** Market is flat. Volatility is low. No clear trend.
*   **The Momentum Bot:** Gets chopped up (Buy high, sell low) repeatedly.
*   **YOUR SYSTEM:**
    *   **Regime:** Detects **SIDEWAYS** or **MEAN_REVERTING**.
    *   **Indicator Selector:** Switches logic. Instead of using breakouts, it uses Bollinger Bands or RSI Mean Reversion.
    *   **Decision:** Buy at Support, Sell at Resistance.
    *   **Outcome:** Capital preservation during noise.

---

## SUMMARY OF DOCTRINE

*   **In Bull Markets:** We trust the Trend. Valuation is ignored.
*   **In Bear Markets:** We trust the Math. Valuation is everything.
*   **In Uncertainty:** We trust Cash.

**This architecture ensures you never miss a bubble, but you never hold the bag when it pops.**

## SYSTEM DECISION FLOW DIAGRAM
The following diagram illustrates the hard-coded logic gates that govern trade execution.

```mermaid
graph TD
    A[Start] --> B[Market Analyst Node]
    B --> C{Detect Regime}
    
    C -- TRENDING_UP --> D[Calculate Relative Strength]
    C -- SIDEWAYS --> D
    C -- TRENDING_DOWN --> D
    
    D --> E[Assign Risk Multiplier]
    E --> F[Fundamental Analysis]
    F --> G[LLM Debate & Report]
    G --> H[Preliminary Decision: BUY/SELL/HOLD]
    
    H --> I{Trend Override Gate}
    
    I -- Signal: SELL --> J{Is Growth > 30% AND Price > 200SMA?}
    J -- YES --> K[Force HOLD: Don't Fight Tape]
    J -- NO --> L[Allow SELL]
    
    I -- Signal: BUY --> M{Insider Veto Gate}
    
    M -- Net Selling > $50M --> N{Is Price < 50SMA?}
    N -- YES --> O[BLOCK BUY: Falling Knife]
    N -- NO --> P[Allow BUY]
    
    L --> Q[Execution]
    K --> Q
    O --> Q
    P --> Q
    
    Q --> R{Active Portfolio Check}
    R -- Position Exists --> S[Calculate Unrealized PnL]
    S --> T{Is PnL < -10%?}
    T -- YES --> U[FORCE LIQUIDATE: Rule 72]
    T -- NO --> V[Maintain State]
```

## SCENARIO LOGIC MATRIX
How the system handles specific market conditions:

| Scenario | Market Regime (SPY) | Asset Regime | Insider Action | Hard Gate Triggered | System Decision |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **"The Bubble Riding"** (e.g. NVDA '23) | UPTREND | UPTREND (Price > SMA) | Selling (Profit Taking) | **Trend Override (Anti-Short)** | **HOLD / BUY** (Ignore valuation fears) |
| **"The Falling Knife"** (e.g. ZOOM '22) | DOWNTREND | DOWNTREND (Price < SMA) | Selling (> $50M) | **Insider Veto** | **BLOCK BUY** (Force Wait) |
| **"The Fake Breakout"** (Bear Market Rally) | DOWNTREND | UPTREND (Weak) | Neutral | Relative Strength = 0.8x | **REDUCE SIZE** (Caution) |
| **"The Crash"** (Portfolio Danger) | VOLATILE | VOLATILE | N/A | **Rule 72 (Stop Loss)** | **LIQUIDATE** (PnL < -10%) |
| **"The Boring Chop"** (Accumulation) | SIDEWAYS | SIDEWAYS | Buying | None | **Trade Range** (Buy Support) |

### SCENARIO VISUALIZATION
```mermaid
graph TD
    %% Define Scenarios
    subgraph "Scenario A: The Bubble (PLTR/NVDA)"
    A1[Market: UP] --> A2[Asset: UP]
    A2 --> A3{Valuation High?}
    A3 -- YES --> A4[Analyst: SELL]
    A4 --> A5{Rules Check}
    A5 -- Growth > 30% --> A6[OVERRIDE: FORCE HOLD]
    end

    subgraph "Scenario B: The Falling Knife (ZOOM)"
    B1[Market: DOWN] --> B2[Asset: DOWN]
    B2 --> B3{Insider Action?}
    B3 -- Net Selling > $50M --> B4[VETO: BLOCK BUY]
    end

    subgraph "Scenario C: The Crash (Survival)"
    C1[Active Position] --> C2{Check PnL}
    C2 -- Loss > -10% --> C3[STOP LOSS TRIGGERED]
    C3 --> C4[LIQUIDATE IMMEDIATE]
    end
    
    style A6 fill:#4caf50,stroke:#333,stroke-width:2px
    style B4 fill:#f44336,stroke:#333,stroke-width:2px
    style C4 fill:#f44336,stroke:#333,stroke-width:2px
```

### Scenario Logic Breakdown

*   **Scenario A (The Momentum Exception):**
    *   **The Conflict:** The Analyst sees a high P/E ratio and screams "Sell!".
    *   **The Resolution:** The Hard Gate checks Growth > 30%. Since this is true, it overrides the "Sell" signal to a HOLD, preventing you from exiting a winner too early.

*   **Scenario B (The Insider Veto):**
    *   **The Conflict:** The price has dropped, and the Analyst thinks it's a "value buy."
    *   **The Resolution:** The Hard Gate checks Net Insider Flow. Seeing >$50M in selling during a downtrend, it activates the VETO, blocking the Buy order to prevent catching a falling knife.

*   **Scenario C (The Stop Loss):**
    *   **The Conflict:** A position is bleeding, but the Analyst (Bull) hopes for a rebound.
    *   **The Resolution:** The State Monitor sees Unrealized PnL < -10%. It bypasses the Analyst entirely and issues a forced LIQUIDATE command to preserve capital.