From dd0013f5c00eb13af9c0d57287076bae97682609 Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Tue, 9 Dec 2025 21:26:40 +0100
Subject: [PATCH] docs: Add mandatory Drift API verification rule for financial
 data
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CRITICAL: Database can be wrong, Drift is source of truth
- Incident Dec 9: Database -9.33, Drift -2.21 (missing .88)
- Root cause: Retry loop chaos caused multi-chunk close, only first recorded
- User mandate: 'drift tells the truth not you' - always verify with API
- Pattern: Query Drift → Compare → Report discrepancies → Correct database
- This is NON-NEGOTIABLE for real money trading system
---
 .github/copilot-instructions.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 82d927d..392f997 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1262,7 +1262,6 @@ docker logs -f trading-bot-v4 | grep "expected log message from fix"
 - Verification: Log messages include "Using original entry price" and "Waiting 5s for Drift state"
 
 ### Critical Path Verification Requirements
-
 **MANDATORY: ALWAYS VERIFY DRIFT STATE BEFORE ANY POSITION OPERATIONS (Dec 9, 2025)**
 - **NEVER trust bot logs, API responses, or database state alone**
 - **ALWAYS query Drift API first:** `curl -X POST /api/trading/sync-positions -H "Authorization: Bearer $API_SECRET_KEY"`
@@ -1272,6 +1271,29 @@ docker logs -f trading-bot-v4 | grep "expected log message from fix"
 - **Why:** Bot logs showed "closed" but Drift still had open position - catastrophic if user wants to keep position open
 - **This is NON-NEGOTIABLE** - verify Drift state before ANY position operation
 
+**MANDATORY: ALWAYS VERIFY DATABASE WITH DRIFT API BEFORE REPORTING NUMBERS (Dec 9, 2025)**
+- **NEVER trust database P&L, exitPrice, or trade details without Drift confirmation**
+- **ALWAYS cross-check database against Drift when reporting losses/gains to user**
+- **Query Drift account health:** `curl http://localhost:3001/api/drift/account-health` for actual balance
+- **Compare database totalCollateral with actual Drift balance** - database can be wrong
+- **Incident (Dec 9, 2025):** Database showed -$19.33 loss, Drift showed -$22.21 actual loss ($2.88 missing)
+- **Root Cause:** Retry loop chaos caused position to close in multiple chunks, only first chunk recorded
+- **User Frustration:** "drift tells the truth not you" - agent trusted incomplete database
+- **Why This Matters:** In real money system, wrong numbers = wrong financial decisions
+- **The Rule:** QUERY DRIFT FIRST → COMPARE TO DATABASE → REPORT DISCREPANCIES → CORRECT DATABASE
+- **Verification Pattern:**
+  ```bash
+  # 1. Check Drift account balance
+  curl -s http://localhost:3001/api/drift/account-health | jq '.totalCollateral'
+  
+  # 2. Query database for trade details
+  psql -c "SELECT realizedPnL FROM Trade WHERE id='...'"
+  
+  # 3. If mismatch: Correct database to match Drift reality
+  psql -c "UPDATE Trade SET realizedPnL = DRIFT_ACTUAL WHERE id='...'"
+  ```
+- **This is NON-NEGOTIABLE** - Drift is source of truth for financial data, not database
+
 **Position Manager Changes:**
 - [ ] Execute test trade with DRY_RUN=false (small size)
 - [ ] Watch docker logs for full TP1 → TP2 → exit cycle