From 1a6e57519acb3d98043d53a4b6731367de56bc8b Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Thu, 24 Jul 2025 12:10:57 +0200
Subject: [PATCH] docs: add critical automation development wisdom to copilot
 instructions

- AI risk management vs manual controls - never mix approaches
- Balance calculation rules using official Drift SDK methods
- Timeframe handling best practices for TradingView integration
- System integration debugging patterns and data flow validation
- Analysis timer implementation with database persistence
- Comprehensive testing and validation patterns for complex systems
- Trading integration validation against actual platform values
- AI analysis output validation for realistic trading parameters

Based on hard-learned lessons from debugging automation system issues.
---
 .github/copilot-instructions.instructions.md | 70 ++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/.github/copilot-instructions.instructions.md b/.github/copilot-instructions.instructions.md
index c3c5fa7..632de8a 100644
--- a/.github/copilot-instructions.instructions.md
+++ b/.github/copilot-instructions.instructions.md
@@ -29,6 +29,43 @@ This is a Next.js 15 App Router application with TypeScript, Tailwind CSS, and A
 
 ## Critical Development Patterns
 
+### Automation System Development Wisdom
+**Key lessons from building and debugging the automation system:**
+
+#### AI Risk Management vs Manual Controls
+- **NEVER mix manual TP/SL inputs with AI automation** - causes conflicts and unpredictable behavior
+- When implementing AI-driven automation, remove all manual percentage inputs from the UI
+- AI should calculate dynamic stop losses and take profits based on market conditions, not user-defined percentages
+- Always validate that UI selections (timeframes, strategies) are properly passed to backend services
+
+#### Balance and P&L Calculation Critical Rules
+- **ALWAYS use Drift SDK's built-in calculation methods** instead of manual calculations
+- Use `driftClient.getUser().getTotalCollateral()` for accurate collateral values
+- Use `driftClient.getUser().getUnrealizedPNL()` for accurate P&L calculations
+- **NEVER use hardcoded prices** (like $195 for SOL) - always get current market data
+- **NEVER use empirical precision factors** - use official SDK precision handling
+- Test balance calculations against actual Drift interface values for validation
+- Unrealized P&L should match position-level P&L calculations
+
+#### Timeframe Handling Best Practices
+- **Always use minute values first** in timeframe mapping to avoid TradingView confusion
+- Example: `'4h': ['240', '240m', '4h', '4H']` - 240 minutes FIRST, then alternatives
+- Validate that UI timeframe selections reach the automation service correctly
+- Log timeframe values at every step to catch hardcoded overrides
+
+#### System Integration Debugging
+- **Always validate data flow** from UI → API → Service → Trading execution
+- Check for hardcoded values that override user selections (especially timeframes)
+- Verify correct protocol usage (Drift vs Jupiter) in trading execution
+- Test cleanup systems regularly - memory leaks kill automation reliability
+- Implement comprehensive logging for multi-step processes
+
+#### Analysis Timer Implementation
+- Store `nextScheduled` timestamps in database for persistence across restarts
+- Calculate countdown dynamically based on current time vs scheduled time
+- Update timer fields in automation status responses for real-time UI updates
+- Format countdown as "XhYm" or "Xm Ys" for better user experience
+
 ### Docker Container Development (Required)
 **All development happens inside Docker containers** using Docker Compose v2. Browser automation requires specific system dependencies that are only available in the containerized environment:
 
@@ -557,6 +594,39 @@ When working with this codebase, prioritize Docker consistency, understand the d
 4. Commit restoration: `git add . && git commit -m "fix: restore automation-v2 functionality" && git push`
 5. Rebuild container to persist restoration
 
+### Testing and Validation Patterns (Critical)
+**Essential validation steps learned from complex automation debugging:**
+
+#### API Response Validation
+- **Always test API responses directly** with curl before debugging UI issues
+- Compare calculated values against actual trading platform values
+- Example: `curl -s http://localhost:9001/api/drift/balance | jq '.unrealizedPnl'`
+- Validate that API returns realistic values (2-5% targets, not 500% gains)
+
+#### Multi-Component System Testing
+- **Test data flow end-to-end**: UI selection → API endpoint → Service logic → Database storage
+- Use browser dev tools to verify API calls match expected parameters
+- Check database updates after automation cycles complete
+- Validate that timer calculations match expected intervals
+
+#### Trading Integration Validation
+- **Never assume trading calculations are correct** - always validate against platform
+- Test with small amounts first when implementing new trading logic
+- Compare bot-calculated P&L with actual platform P&L values
+- Verify protocol selection (Drift vs Jupiter) matches intended trading method
+
+#### AI Analysis Output Validation
+- **Always check AI responses for realistic values** before using in trading
+- AI can return absolute prices when percentages are expected - validate data types
+- Log AI analysis results to catch unrealistic take profit targets (>50% gains)
+- Implement bounds checking on AI-generated trading parameters
+
+#### Cleanup System Monitoring
+- **Test cleanup functionality after every automation cycle**
+- Monitor memory usage patterns to catch cleanup failures early
+- Verify that cleanup triggers properly after analysis completion
+- Check for zombie browser processes that indicate cleanup issues
+
 ### Successful Implementation Workflow
 **After completing any feature or fix:**
 ```bash