docs: Document Stop Hunt Revenge System (Nov 20, 2025)

Complete documentation for automated revenge trading system

Sections added:
- Purpose and architecture (4-hour window, 1.2x sizing, quality 85+)
- Revenge conditions (price reversal logic for LONG/SHORT)
- How it works (7-step process from recording to execution)
- Database schema (StopHunt table, 20 fields, 4 indexes)
- Code components (tracker service, startup integration, Position Manager)
- Telegram notification format
- Singleton pattern usage
- Startup behavior
- Common pitfalls (7 issues to avoid)
- Real-world use case (Nov 20 motivation)
- Deployment status
- Git commits

Location: Added between Telegram Notifications and Integration Points
File: .github/copilot-instructions.md
Lines: ~140 lines of comprehensive documentation

.github/copilot-instructions.md

@@ -3571,6 +3571,136 @@ All technical improvements must align with current phase objectives (see top of
 - b1ca454 "feat: Add Telegram notifications for position closures" (Nov 16, 2025)
 - 79e7ffe "feat: Add Telegram notification for TP1 partial closes" (Nov 20, 2025)
 
+## Stop Hunt Revenge System (Nov 20, 2025)
+
+**Purpose:** Automatically re-enters positions after high-quality signals (score 85+) get stopped out, when price reverses back through original entry. Recovers losses faster by using 1.2x position size.
+
+**Architecture:**
+- **4-Hour Revenge Window:** Monitors for price reversal within 4 hours of stop-out
+- **Quality Threshold:** Only quality score 85+ signals eligible (top-tier setups)
+- **Position Size:** 1.2× original size (recover losses + profit faster)
+- **One Revenge Per Stop Hunt:** Maximum 1 revenge trade per stop-out event
+- **Monitoring Interval:** 30-second price checks for active stop hunts
+- **Database:** StopHunt table (20 fields, 4 indexes) tracks all stop hunt events
+
+**Revenge Conditions:**
+```typescript
+// LONG stopped above entry → Revenge when price drops back below entry
+if (direction === 'long' && currentPrice < originalEntryPrice - (0.005 * originalEntryPrice)) {
+  // Price dropped 0.5% below entry → Stop hunt reversal confirmed
+  executeRevengeTrade()
+}
+
+// SHORT stopped below entry → Revenge when price rises back above entry
+if (direction === 'short' && currentPrice > originalEntryPrice + (0.005 * originalEntryPrice)) {
+  // Price rose 0.5% above entry → Stop hunt reversal confirmed
+  executeRevengeTrade()
+}
+```
+
+**How It Works:**
+1. **Recording:** Position Manager detects SL close with `signalQualityScore >= 85`
+2. **Database:** Creates StopHunt record with entry price, quality score, ADX, ATR
+3. **Monitoring:** Background job checks every 30 seconds for price reversals
+4. **Trigger:** Price crosses back through entry + 0.5% buffer within 4 hours
+5. **Execution:** Calls `/api/trading/execute` with 1.2× position size, same direction
+6. **Telegram:** Sends "🔥 REVENGE TRADE ACTIVATED" notification
+7. **Completion:** Updates database with revenge trade ID, marks revengeExecuted=true
+
+**Database Schema (StopHunt table):**
+- **Original Trade:** `originalTradeId`, `symbol`, `direction`, `stopHuntPrice`, `originalEntryPrice`
+- **Quality Metrics:** `originalQualityScore` (85+), `originalADX`, `originalATR`
+- **Financial:** `stopLossAmount` (how much user lost), `revengeEntryPrice`
+- **Timing:** `stopHuntTime`, `revengeTime`, `revengeExpiresAt` (4 hours after stop)
+- **Tracking:** `revengeTradeId`, `revengeExecuted`, `revengeWindowExpired`
+- **Price Extremes:** `highestPriceAfterStop`, `lowestPriceAfterStop` (for analysis)
+- **Indexes:** symbol, revengeExecuted, revengeWindowExpired, stopHuntTime
+
+**Code Components:**
+```typescript
+// lib/trading/stop-hunt-tracker.ts (293 lines)
+class StopHuntTracker {
+  recordStopHunt()           // Save stop hunt to database
+  startMonitoring()          // Begin 30-second checks
+  checkRevengeOpportunities()// Find active stop hunts needing revenge
+  shouldExecuteRevenge()     // Validate price reversal conditions
+  executeRevengeTrade()      // Call execute API with 1.2x size
+}
+
+// lib/startup/init-position-manager.ts (integration)
+await startStopHuntTracking()  // Initialize on server startup
+
+// lib/trading/position-manager.ts (recording - ready for next deployment)
+if (reason === 'SL' && trade.signalQualityScore >= 85) {
+  const tracker = getStopHuntTracker()
+  await tracker.recordStopHunt({ /* trade details */ })
+}
+```
+
+**Telegram Notification Format:**
+```
+🔥 REVENGE TRADE ACTIVATED 🔥
+
+Original Trade:
+📍 Entry: $142.48 SHORT
+❌ Stopped Out: -$138.35
+🎯 Quality Score: 90 (ADX 26)
+
+Revenge Trade:
+📍 Re-Entry: $138.20 SHORT
+💪 Size: 1.2× original ($10,020 vs $8,350)
+🎯 Targets: TP1 +0.86%, TP2 +1.72%
+
+Stop Hunt Reversal Confirmed ✓
+Time to get our money back!
+```
+
+**Singleton Pattern:**
+```typescript
+// CORRECT: Use getter function
+const tracker = getStopHuntTracker()
+await tracker.recordStopHunt({ /* params */ })
+
+// WRONG: Direct instantiation creates multiple instances
+const tracker = new StopHuntTracker()  // ❌ Don't do this
+```
+
+**Startup Behavior:**
+- Container starts → Checks database for active stop hunts (not expired, not executed)
+- If activeCount > 0: Starts monitoring immediately, logs count
+- If activeCount = 0: Logs "No active stop hunts - tracker will start when needed"
+- Monitoring auto-starts when Position Manager records new stop hunt
+
+**Common Pitfalls:**
+1. **Database query hanging:** Fixed with try-catch error handling (Nov 20, 2025)
+2. **Import path errors:** Use `'../database/trades'` not `'../database/client'`
+3. **Multiple instances:** Always use `getStopHuntTracker()` singleton getter
+4. **Quality threshold:** Only 85+ eligible, don't lower without user approval
+5. **Position size math:** 1.2× means execute with `originalSize * 1.2`, not +20%
+6. **Revenge window:** 4 hours from stop-out, not from signal generation
+7. **One revenge limit:** Check `revengeExecuted` flag before executing again
+
+**Real-World Use Case (Nov 20, 2025 motivation):**
+- User had v8 signal: Quality 90, ADX 26, called exact top at $141.37
+- Stopped at $142.48 for -$138.35 loss
+- Price then dropped to $131.32 (8.8% move)
+- Missed +$490 potential profit if not stopped
+- Revenge system would've re-entered SHORT at ~$141.50, captured $7-8+ profit
+
+**Deployment Status:**
+- ✅ Database schema created (StopHunt table with indexes)
+- ✅ Tracker service implemented (293 lines, 8 methods)
+- ✅ Startup integration active (initializes on container start)
+- ✅ Error handling added (try-catch for database operations)
+- ✅ Clean production logs (DEBUG logs removed)
+- ⏳ Position Manager recording (code ready, deploys on next Position Manager change)
+- ⏳ Real-world validation (waiting for first quality 85+ stop-out)
+
+**Git Commits:**
+- 702e027 "feat: Stop Hunt Revenge System - DEPLOYED (Nov 20, 2025)"
+- Fixed import paths, added error handling, removed debug logs
+- Full system operational, monitoring active
+
 ## Integration Points
 
 - **n8n:** Expects exact response format from `/api/trading/execute` (see n8n-complete-workflow.json)