MQL4/.github/MQL4_INSTRUCTIONS_SUMMARY.md

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.