From 6ef5fea41a21762fad41f50a98be49b1c9c86e28 Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Tue, 11 Nov 2025 12:02:22 +0100
Subject: [PATCH] docs: add essential SQL queries to AI agent instructions

Added SQL Analysis Queries section with:
- Phase 1 monitoring queries (count, score distribution, recent signals)
- Phase 2 comparison queries (blocked vs executed trades)
- Pattern analysis queries (range extremes, ADX distribution)

Benefits:
- AI agents have immediate access to standard queries
- Consistent analysis approach each time
- No need to context-switch to separate docs
- Quick reference for common investigations

Includes usage pattern guidance and reference to full docs.
---
 .github/copilot-instructions.md | 107 ++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 0002fac..5093975 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -426,6 +426,113 @@ docker exec trading-bot-postgres psql -U postgres -d trading_bot_v4 -c "\dt"
 # Click "Test LONG" or "Test SHORT"
 ```
 
+## SQL Analysis Queries
+
+Essential queries for monitoring signal quality and blocked signals. Run via:
+```bash
+docker exec trading-bot-postgres psql -U postgres -d trading_bot_v4 -c "YOUR_QUERY"
+```
+
+### Phase 1: Monitor Data Collection Progress
+```sql
+-- Check blocked signals count (target: 10-20 for Phase 2)
+SELECT COUNT(*) as total_blocked FROM "BlockedSignal";
+
+-- Score distribution of blocked signals
+SELECT 
+  CASE 
+    WHEN signalQualityScore >= 60 THEN '60-64 (Close Call)'
+    WHEN signalQualityScore >= 55 THEN '55-59 (Marginal)'
+    WHEN signalQualityScore >= 50 THEN '50-54 (Weak)'
+    ELSE '0-49 (Very Weak)'
+  END as tier,
+  COUNT(*) as count,
+  ROUND(AVG(signalQualityScore)::numeric, 1) as avg_score
+FROM "BlockedSignal"
+WHERE blockReason = 'QUALITY_SCORE_TOO_LOW'
+GROUP BY tier
+ORDER BY MIN(signalQualityScore) DESC;
+
+-- Recent blocked signals with full details
+SELECT 
+  symbol,
+  direction,
+  signalQualityScore as score,
+  ROUND(adx::numeric, 1) as adx,
+  ROUND(atr::numeric, 2) as atr,
+  ROUND(pricePosition::numeric, 1) as pos,
+  ROUND(volumeRatio::numeric, 2) as vol,
+  blockReason,
+  TO_CHAR(createdAt, 'MM-DD HH24:MI') as time
+FROM "BlockedSignal"
+ORDER BY createdAt DESC
+LIMIT 10;
+```
+
+### Phase 2: Compare Blocked vs Executed Trades
+```sql
+-- Compare executed trades in 60-69 score range
+SELECT 
+  signalQualityScore as score,
+  COUNT(*) as trades,
+  ROUND(AVG(realizedPnL)::numeric, 2) as avg_pnl,
+  ROUND(SUM(realizedPnL)::numeric, 2) as total_pnl,
+  ROUND(100.0 * SUM(CASE WHEN realizedPnL > 0 THEN 1 ELSE 0 END) / COUNT(*)::numeric, 1) as win_rate
+FROM "Trade"
+WHERE exitReason IS NOT NULL
+  AND signalQualityScore BETWEEN 60 AND 69
+GROUP BY signalQualityScore
+ORDER BY signalQualityScore;
+
+-- Block reason breakdown
+SELECT 
+  blockReason,
+  COUNT(*) as count,
+  ROUND(AVG(signalQualityScore)::numeric, 1) as avg_score
+FROM "BlockedSignal"
+GROUP BY blockReason
+ORDER BY count DESC;
+```
+
+### Analyze Specific Patterns
+```sql
+-- Blocked signals at range extremes (price position)
+SELECT 
+  direction,
+  signalQualityScore as score,
+  ROUND(pricePosition::numeric, 1) as pos,
+  ROUND(adx::numeric, 1) as adx,
+  ROUND(volumeRatio::numeric, 2) as vol,
+  symbol,
+  TO_CHAR(createdAt, 'MM-DD HH24:MI') as time
+FROM "BlockedSignal"
+WHERE blockReason = 'QUALITY_SCORE_TOO_LOW'
+  AND (pricePosition < 10 OR pricePosition > 90)
+ORDER BY signalQualityScore DESC;
+
+-- ADX distribution in blocked signals
+SELECT 
+  CASE 
+    WHEN adx >= 25 THEN 'Strong (25+)'
+    WHEN adx >= 20 THEN 'Moderate (20-25)'
+    WHEN adx >= 15 THEN 'Weak (15-20)'
+    ELSE 'Very Weak (<15)'
+  END as adx_tier,
+  COUNT(*) as count,
+  ROUND(AVG(signalQualityScore)::numeric, 1) as avg_score
+FROM "BlockedSignal"
+WHERE blockReason = 'QUALITY_SCORE_TOO_LOW'
+  AND adx IS NOT NULL
+GROUP BY adx_tier
+ORDER BY MIN(adx) DESC;
+```
+
+**Usage Pattern:**
+1. Run "Monitor Data Collection" queries weekly during Phase 1
+2. Once 10+ blocked signals collected, run "Compare Blocked vs Executed" queries
+3. Use "Analyze Specific Patterns" to identify optimization opportunities
+4. Full query reference: `BLOCKED_SIGNALS_TRACKING.md`
+
 ## Common Pitfalls
 
 1. **Prisma not generated in Docker:** Must run `npx prisma generate` in Dockerfile BEFORE `npm run build`