From 9d2055e59c459b029accdf1b6d8eced0fe21b5df Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Mon, 1 Dec 2025 00:12:28 +0100
Subject: [PATCH] docs: Add mandatory documentation workflow - git commit must
 go hand-in-hand with documentation

---
 .github/copilot-instructions.md | 103 +++++++++++++++++++++++++++++++-
 1 file changed, 102 insertions(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 0dc9cad..3ae4327 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -173,7 +173,108 @@ Change → Code → Test → Git Commit → UPDATE COPILOT-INSTRUCTIONS.MD → G
 
 ---
 
-## 📊 1-Minute Data Collection System (Nov 27, 2025)
+## � DOCUMENTATION + GIT COMMIT: INSEPARABLE WORKFLOW
+
+**⚠️ CRITICAL: DOCUMENTATION IS NOT OPTIONAL - IT'S PART OF THE COMMIT**
+
+### Universal Rule: Documentation Goes Hand-in-Hand with Git Commits
+
+**MANDATORY workflow for ALL valuable insights and recent developments:**
+
+```bash
+# WRONG (incomplete):
+git add [files]
+git commit -m "feat: Added new feature"
+git push
+# ❌ INCOMPLETE - No documentation!
+
+# CORRECT (complete):
+git add [files]
+git commit -m "feat: Added new feature"
+# NOW: Update copilot-instructions.md with insights/learnings/patterns
+git add .github/copilot-instructions.md
+git commit -m "docs: Document new feature insights and patterns"
+git push
+# ✅ COMPLETE - Code + Documentation committed together
+```
+
+**What qualifies as "valuable insights" requiring documentation:**
+
+1. **System behaviors discovered** during implementation or debugging
+2. **Lessons learned** from bugs, failures, or unexpected outcomes
+3. **Design decisions** and WHY specific approaches were chosen
+4. **Integration patterns** that future changes must follow
+5. **Data integrity rules** discovered through analysis
+6. **Common mistakes** that cost time/money to discover
+7. **Verification procedures** that proved critical
+8. **Performance insights** from production data
+
+**Why this matters:**
+
+- **Knowledge preservation:** Insights are lost without documentation
+- **Future AI agents:** Need context to avoid repeating mistakes
+- **Time savings:** Documented patterns prevent re-investigation
+- **Financial protection:** Trading system knowledge prevents costly errors
+- **User expectation:** "please add in the documentation" shouldn't be necessary
+
+**The mindset:**
+
+- Every git commit = potential learning opportunity
+- If you learned something valuable → document it
+- If you solved a tricky problem → document the solution
+- If you discovered a pattern → document the pattern
+- **Documentation is not separate work - it's part of completing the task**
+
+**Examples of commits requiring documentation:**
+
+```bash
+# Scenario 1: Bug fix reveals system behavior
+git commit -m "fix: Correct P&L calculation for partial closes"
+# → Document: Why averageExitPrice doesn't work, must use realizedPnL field
+# → Add to: Common Pitfalls section
+
+# Scenario 2: New feature with integration requirements
+git commit -m "feat: Smart Entry Validation Queue system"
+# → Document: How it works, when it triggers, integration points, monitoring
+# → Add to: Common Pitfalls or Critical Components section
+
+# Scenario 3: Performance optimization reveals insight
+git commit -m "perf: Adaptive leverage based on quality score"
+# → Document: Quality thresholds, why tiers chosen, expected impact
+# → Add to: Configuration System or relevant feature section
+
+# Scenario 4: Data analysis reveals filtering requirement
+git commit -m "fix: Exclude manual trades from indicator analysis"
+# → Document: signalSource field, SQL filtering patterns, why it matters
+# → Add to: Important fields and Analysis patterns sections
+```
+
+**Red flags indicating missing documentation:**
+
+- ❌ User says: "please add in the documentation"
+- ❌ User asks: "is this documented?"
+- ❌ User asks: "everything documented?"
+- ❌ Code commit has no corresponding documentation commit
+- ❌ Bug fix with no Common Pitfall entry
+- ❌ New feature with no integration notes
+
+**Integration with existing sections:**
+
+- **Common Pitfalls:** Add bugs/mistakes/lessons learned
+- **Critical Components:** Add new systems/services
+- **Configuration System:** Add new ENV variables
+- **When Making Changes:** Add new development patterns
+- **API Endpoints:** Add new routes and their purposes
+
+**Remember:**
+
+Documentation is not bureaucracy - it's **protecting future profitability** by preserving hard-won knowledge. In a real money trading system, forgotten lessons = repeated mistakes = financial losses.
+
+**Git commit + Documentation = Complete work. One without the other = Incomplete.**
+
+---
+
+## �📊 1-Minute Data Collection System (Nov 27, 2025)
 
 **Purpose:** Real-time market data collection via TradingView 1-minute alerts for Phase 7.1/7.2/7.3 enhancements