From aafc4ce506298765f47b7301c55c8727a0cde902 Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Fri, 19 Dec 2025 09:32:21 +0100
Subject: [PATCH] docs: Add orderbook shadow logging to copilot instructions

- Added comprehensive section to Critical Components (#2)
- Ensures all future AI agents aware of orderbook feature
- Documents implementation, scope (trade-time only), status
- Cross-references ORDERBOOK_SHADOW_LOGGING.md for details
- Status: Deployed Dec 19, 2025, Phase 1 complete
- Awaiting validation with first 50-100 trades
---
 .github/copilot-instructions.md | 63 ++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index b2185fa..a8abf35 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -2361,7 +2361,68 @@ TX: 5Yx2Fm8vQHKLdPaw...
 
 **Code location:** `app/api/trading/execute/route.ts` lines 322-445
 
-### 2. Signal Quality Scoring (`lib/trading/signal-quality.ts`)
+### 2. Orderbook Shadow Logging System (Dec 19, 2025)
+**Purpose:** Oracle-based orderbook metrics captured at trade execution for future liquidity analysis and real orderbook API integration
+
+**Phase 1 Implementation (DEPLOYED):**
+- **Service:** `lib/drift/orderbook-service.ts` - Singleton with `getMetricsForDirection()` method
+- **Integration:** `app/api/trading/execute/route.ts` lines 1037-1053 - Captures orderbook at trade execution
+- **Storage:** Trade table with 7 orderbook columns (added Dec 19, 2025):
+  * `obSpreadBps` - Bid-ask spread in basis points (estimated)
+  * `obImbalance` - Buy/sell pressure ratio (-1 to 1)
+  * `obOppDepth0_2pctUSD` - Opposite side liquidity within 0.2% of mid
+  * `obSameDepth0_2pctUSD` - Same side liquidity within 0.2% of mid
+  * `obImpactBpsAtNotional` - Price impact for trade size
+  * `obLargestOppWallBps` - Largest resistance level (bps from mid)
+  * `obLargestOppWallUSD` - Size of largest resistance wall
+- **ENV Config:** `ENABLE_ORDERBOOK_LOGGING` (defaults true)
+
+**CRITICAL Scope:**
+- **Captured:** Trade execution only (when `/api/trading/execute` runs)
+- **NOT captured:** 1-minute market data feed (`/api/trading/market-data`)
+- **Frequency:** 3-5 orderbook snapshots per day (when trades happen)
+- **Rationale:** Minimize API overhead, capture relevant data (orderbook state at actual trade moment)
+
+**Data Source (Phase 1):**
+- **Oracle-based estimates:** Uses Drift Protocol price oracle with 2bps spread assumption
+- **Purpose:** Establish baseline metrics for comparison
+- **Validation goal:** Collect 50-100 trades to identify patterns
+- **Phase 2 roadmap:** Replace with real orderbook API (Hyperliquid CEX, Jupiter DEX)
+
+**Key Features:**
+- Singleton pattern: Always use `getOrderbookService()` - never instantiate directly
+- Automatic capture: No manual intervention needed, happens on every trade
+- Feature flag: Can be disabled via `ENABLE_ORDERBOOK_LOGGING=false` in .env
+- Database persistence: All metrics stored in Trade table for historical analysis
+
+**SQL Query for Analysis:**
+```sql
+SELECT 
+  "symbol", "direction", "obSpreadBps", "obImbalance", 
+  "obImpactBpsAtNotional", "realizedPnL", "createdAt"
+FROM "Trade" 
+WHERE "obSpreadBps" IS NOT NULL 
+ORDER BY "createdAt" DESC 
+LIMIT 50;
+```
+
+**Future Enhancements (Phase 1.5 - User Declined Dec 19, 2025):**
+- Periodic orderbook monitoring (every 1 minute) - Not implemented
+- Tradeoff: 1,440 API calls/day vs. 3-5/day, minimal benefit for Phase 1 validation
+- User confirmed trade-time capture sufficient for now
+
+**Documentation:**
+- Complete details: `/home/icke/traderv4/docs/ORDERBOOK_SHADOW_LOGGING.md`
+- Git commits: 6990f20 (implementation), 67dde80 (scope clarification)
+- Status: ✅ Deployed and operational, awaiting first trade with data
+
+**Why This Matters:**
+- **Liquidity awareness:** Understand market depth when entering trades
+- **Pattern identification:** Correlate spread/imbalance with trade outcomes
+- **Phase 2 preparation:** Baseline for comparing oracle vs. real orderbook data
+- **Smart entry optimization:** Future real-time orderbook monitoring for optimal timing
+
+### 3. Signal Quality Scoring (`lib/trading/signal-quality.ts`)
 **Purpose:** Unified quality validation system that scores trading signals 0-100 based on 5 market metrics
 
 **Timeframe-aware thresholds:**