docs: Add mandatory Drift API verification rule for financial data

- 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
This commit is contained in:
mindesbunister
2025-12-09 21:26:40 +01:00
parent 1ed909c661
commit dd0013f5c0

View File

@@ -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