# MQL4 Instruction Files - Creation Summary

## Overview
Created comprehensive MQL4 instruction files based on real-world experience from developing the MultiTimeframeZone EA. These files mirror the existing MQL5 instruction structure and provide AI agents with proper context for MQL4 development.

---

## Files Created

### 1. mql4-syntax-critical.instructions.md
**Purpose:** Critical syntax rules that prevent compilation errors  
**Location:** `.github/instructions/mql4-syntax-critical.instructions.md`  
**Apply To:** `**/*.mq4,**/MQL4/**/*.mqh`

**Key Sections:**
- Loop Variable Declaration (must declare before for-loop)
- Array Declarations and Sizing
- Order Functions and Trade Operations
- Price and Market Information Functions
- Object Properties and Chart Objects
- String Operations and Formatting
- Time and Date Functions
- Account and Trade Information
- Global Variables vs Input Parameters
- Common Pitfalls and Best Practices
- Compilation and Testing Checklists
- MQL4 vs MQL5 Comparison Table

**Critical Rules Covered:**
- ✅ Declare loop variables BEFORE for-loop: `int i; for(i=0; i<n; i++)`
- ✅ Use `OrderSend()`, `OrderClose()`, `OrderModify()` for trading
- ✅ Use `AccountBalance()`, `AccountEquity()` (not `AccountInfoDouble()`)
- ✅ Always call `OrderSelect()` before accessing order properties
- ✅ Normalize all prices with `NormalizeDouble(price, Digits)`
- ✅ Handle errors with `GetLastError()` and `ErrorDescription()`

---

### 2. mql4-experts.instructions.md
**Purpose:** Expert Advisor development guidelines  
**Location:** `.github/instructions/mql4-experts.instructions.md`  
**Apply To:** `**/MQL4/Experts/_Thivyam/**/*.mq4`

**Key Sections:**
- EA Structure and Organization
- Initialization (`OnInit()`) best practices
- Deinitialization (`OnDeinit()`) cleanup
- Main Trading Logic (`OnTick()`) patterns
- Multi-Timeframe Execution
- Trade Execution Templates
- Position Monitoring
- Risk Management (MANDATORY dynamic lot sizing)
- Pattern Detection (Engulfing patterns)
- Zone Management with Arrays
- Zone Drawing on Charts
- Error Handling
- Visual Display (Info Panels)
- Testing and Validation
- Demo/Trial Version Implementation

**Real-World Examples:**
- Complete once-per-bar execution pattern
- Multi-timeframe bar detection (H4, M30, M15)
- Pending order placement with full validation
- Position monitoring with trailing stops
- Dynamic lot calculation based on risk %
- Zone storage using fixed-size arrays
- Demo expiry logic

---

### 3. mql4-indicators.instructions.md
**Purpose:** Custom indicator development guidelines  
**Location:** `.github/instructions/mql4-indicators.instructions.md`  
**Apply To:** `**/MQL4/Indicators/_Thivyam/**/*.mq4`

**Key Sections:**
- Indicator Structure and Property Directives
- Buffer Declaration (Plot vs Calculation Buffers)
- OnCalculate() Function Signature and Patterns
- Efficient Calculation Pattern (using prev_calculated)
- Drawing Styles (Line, Histogram, Arrow, etc.)
- Multi-Buffer Indicators
- Arrow Drawing and Symbol Codes
- Multi-Timeframe Indicators
- Using Other Indicators (iMA, iRSI, iStochastic)
- Zone Detection Indicator Example
- Alerts and Notifications
- Performance Optimization
- Repaint vs Non-Repaint Logic
- Common Pitfalls

**Complete Examples:**
- Moving Average Indicator
- Multi-Buffer Signal Indicator
- Arrow-Based Signal Indicator
- Supply/Demand Zone Indicator
- Support/Resistance Detection

---

### 4. mql4-scripts.instructions.md
**Purpose:** Script development guidelines  
**Location:** `.github/instructions/mql4-scripts.instructions.md`  
**Apply To:** `**/MQL4/Scripts/_Thivyam/**/*.mq4`

**Key Sections:**
- Script Overview (OnStart vs OnTick)
- Script Structure
- Common Script Types:
  - Close All Orders Script
  - Delete All Objects Script
  - Modify All Orders Script
  - Account Information Script
  - Draw Support/Resistance Lines Script
- Best Practices:
  - User Confirmation
  - Progress Reporting
  - Error Handling
  - File Operations

**Complete Working Scripts:**
Each script type includes full, production-ready code with:
- Input parameter validation
- User confirmation dialogs
- Error handling
- Progress feedback
- Result reporting

---

## Updated Files

### copilot-instructions.md
**Changes Made:**

1. **Added Section 5: Language-Specific Instructions**
   - Clear routing to MQL5 vs MQL4 instruction files
   - Mandatory reading requirements before coding
   - Key rules summary for each language
   - Python and compilation verification guidance

2. **Reorganized Section 6: Information Sourcing Protocol**
   - Priority 1: Language-specific instruction files
   - Priority 2: Internal documentation
   - Priority 3: Official MQL5/MQL4 channels
   - Priority 4: General internet search

3. **Added Section 7: Key Differences MQL4 vs MQL5**
   - Side-by-side comparison table
   - Critical differences highlighted
   - "Golden Rule" for language separation

4. **Added Section 8: Workflow for Agentic AI Coders**
   - 9-step process from identification to commit
   - Emphasis on reading instructions first
   - Compilation and testing requirements

5. **Added Section 9: Common Pitfalls to Avoid**
   - Universal pitfalls (both languages)
   - MQL4-specific pitfalls
   - MQL5-specific pitfalls

6. **Added Section 10: Success Checklist**
   - Pre-completion verification checklist
   - 11 critical items to verify before marking task complete

---

## Key Learnings from MultiTimeframeZone EA

The instruction files incorporate these real-world lessons:

### Syntax Issues Discovered
1. **Loop Variable Declaration**: Must declare before for-loop in both MQL4 and MQL5
2. **Error Handling**: All trade operations need GetLastError() checks
3. **Price Normalization**: Critical for avoiding Error 130 (Invalid Stops)
4. **Margin Checking**: Must verify before placing orders to avoid Error 134

### Trade Execution Issues Fixed
1. **Order Type Error**: Used OP_BUYSTOP instead of OP_BUYLIMIT (wrong order type)
2. **Stop Loss Logic**: SL should be at zone boundary, not zone opposite end
3. **Price Validation**: Entry price must respect MODE_STOPLEVEL distance
4. **Lot Normalization**: Must use broker's MODE_LOTSTEP and limits

### Zone Management Issues Resolved
1. **Zone Lifecycle**: H4 zones need proper break and reversal tracking
2. **Zone Deletion**: M15 zones must be deleted after order closes
3. **Visual Styling**: Rectangle objects need proper OBJPROP_STYLE settings
4. **Zone Drawing**: Use OBJPROP_BACK=false to avoid filled rectangles

### Risk Management Issues Addressed
1. **No Hardcoded Lots**: Always calculate based on risk %
2. **Dynamic SL Distance**: Calculate from zone size or ATR
3. **Margin Validation**: Check before every trade
4. **Demo Expiry**: Implement time-limited trial logic

---

## Instruction File Structure

All instruction files follow this structure:

```
---
applyTo: "file_pattern"
---
# Title

## CRITICAL: Syntax Compliance
[Reference to critical syntax file]

## Sections
[Organized by topic]

### Code Examples
✅ CORRECT - [Description]
❌ WRONG - [Description]

## Best Practices
[Bullet points]

## Common Pitfalls
[What to avoid]

## Summary
[Checklist format]
```

---

## Usage by AI Agents

When an AI agent is asked to work with MQL code:

1. **File Type Detection**: Check file extension (.mq4 vs .mq5)
2. **Read Critical Syntax**: Read `mql4-syntax-critical.instructions.md` or `mql5-syntax-critical.instructions.md`
3. **Read Type-Specific**: Read experts/indicators/scripts instructions based on code type
4. **Follow Patterns**: Use the code examples as templates
5. **Verify Checklist**: Check all items before marking complete
6. **Compile & Test**: Use compilation-verification.instructions.md

---

## Benefits

### For AI Agents:
- Clear, unambiguous rules based on real-world experience
- Complete working examples to use as templates
- Common pitfalls explicitly documented
- Compilation verification process documented

### For Human Developers:
- Comprehensive reference for MQL4 development
- Side-by-side MQL4 vs MQL5 comparisons
- Production-ready code examples
- Testing and validation checklists

### For Project Quality:
- Consistent code style across all MQL4 projects
- Reduced compilation errors
- Fewer runtime errors
- Better error handling

---

## Files Added to Repository

```
.github/
├── copilot-instructions.md (UPDATED)
└── instructions/
    ├── mql4-syntax-critical.instructions.md (NEW)
    ├── mql4-experts.instructions.md (NEW)
    ├── mql4-indicators.instructions.md (NEW)
    └── mql4-scripts.instructions.md (NEW)
```

Total Lines Added: ~2,740 lines of comprehensive documentation

---

## Next Steps for Users

1. **Review the Instructions**: Familiarize yourself with the new instruction files
2. **Test with New Projects**: Use these instructions when creating new MQL4 code
3. **Refine as Needed**: Update instructions based on new learnings
4. **Share with Team**: Ensure all developers follow these guidelines

---

## Maintenance

These instruction files should be updated when:
- New syntax issues are discovered
- Better patterns are identified
- MQL4 language updates are released
- Team conventions change

Keep the instruction files synchronized with real-world development experience!

---

## Conclusion

The MQL4 instruction files provide comprehensive, battle-tested guidance for AI agents developing trading systems. They incorporate real-world lessons from the MultiTimeframeZone EA project and ensure consistent, high-quality code across all _Thivyam projects.

**Key Achievement:** AI agents now have the same level of instruction quality for MQL4 as they had for MQL5, ensuring consistent development standards across both platforms.