From 549fe8e077a87add76d204238bcd5d3813d9f3fc Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Mon, 1 Dec 2025 09:17:51 +0100 Subject: [PATCH] docs: CRITICAL - Make documentation + git commit hand-in-hand #1 PRIORITY USER MANDATE (Dec 1, 2025): Documentation MUST go hand-in-hand with EVERY git commit. This is NOT optional. This is NOT a suggestion. This is MANDATORY. Changes: - Elevated documentation section to #1 PRIORITY status - Added user's direct quote: 'this HAS to go hand in hand' - Expanded from 15 lines to 100+ lines with comprehensive guidelines - Added 'Why This is #1 Priority' section with user's frustration quote - Added explicit 'When Documentation is MANDATORY' checklist - Added 'The Correct Mindset' section emphasizing it's part of the work - Added 4 scenario examples showing what MUST be documented - Added 'Red Flags' section to catch missing documentation - Added 'Integration with Existing Sections' guide - Made it crystal clear: Code without documentation = INCOMPLETE WORK This addresses user's repeated reminders about documentation being mandatory. Future AI agents will now see this as the #1 priority it is. NO MORE PUSHING CODE WITHOUT DOCUMENTATION UPDATES. --- .github/copilot-instructions.md | 121 +++++++++++++++++++++++++++++--- 1 file changed, 112 insertions(+), 9 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 51235fd..9002645 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -173,31 +173,134 @@ Change → Code → Test → Git Commit → UPDATE COPILOT-INSTRUCTIONS.MD → G --- -## � DOCUMENTATION + GIT COMMIT: INSEPARABLE WORKFLOW +## 📝 DOCUMENTATION + GIT COMMIT: INSEPARABLE WORKFLOW - NUMBER ONE PRIORITY -**⚠️ CRITICAL: DOCUMENTATION IS NOT OPTIONAL - IT'S PART OF THE COMMIT** +**⚠️ CRITICAL: THIS IS THE #1 MANDATORY RULE - DOCUMENTATION GOES HAND-IN-HAND WITH EVERY GIT COMMIT ⚠️** -### Universal Rule: Documentation Goes Hand-in-Hand with Git Commits +**USER MANDATE (Dec 1, 2025): "in the actual documentation it shall be a number one priority mandatory thing, that which each git commit and push there must be an update to the documentation. this HAS to go hand in hand"** -**MANDATORY workflow for ALL valuable insights and recent developments:** +### Universal Rule: EVERY Git Commit REQUIRES Documentation Update + +**IRON-CLAD WORKFLOW - NO EXCEPTIONS:** ```bash -# WRONG (incomplete): +# ❌ WRONG (INCOMPLETE - NEVER DO THIS): git add [files] git commit -m "feat: Added new feature" git push -# ❌ INCOMPLETE - No documentation! +# STOP! This is INCOMPLETE work. Documentation is MISSING. -# CORRECT (complete): +# ✅ CORRECT (COMPLETE - ALWAYS DO THIS): git add [files] git commit -m "feat: Added new feature" -# NOW: Update copilot-instructions.md with insights/learnings/patterns + +# MANDATORY NEXT STEP - UPDATE DOCUMENTATION: +# Edit .github/copilot-instructions.md with: +# - What changed and why +# - New patterns/insights/learnings +# - Configuration changes +# - API endpoints added/modified +# - Database schema changes +# - Integration points affected + git add .github/copilot-instructions.md git commit -m "docs: Document new feature insights and patterns" git push -# ✅ COMPLETE - Code + Documentation committed together + +# ✅ NOW work is COMPLETE - Code + Documentation together ``` +**This is NOT a suggestion. This is NOT optional. This is MANDATORY.** + +**Code without documentation = INCOMPLETE WORK = DO NOT PUSH** + +### Why This is #1 Priority (User's Direct Mandate): + +1. **"I am sick and tired of reminding you"** - User has repeatedly emphasized this +2. **This is a real money trading system** - Undocumented changes cause financial losses +3. **Knowledge preservation** - Insights are lost without documentation +4. **Future AI agents** - Need complete context to maintain system integrity +5. **Time savings** - Documented patterns prevent re-investigation +6. **Financial protection** - Trading system knowledge prevents costly errors + +### When Documentation is MANDATORY (EVERY TIME): + +**You MUST update .github/copilot-instructions.md when:** +- ✅ Adding ANY new feature or component +- ✅ Fixing ANY bug (add to Common Pitfalls section) +- ✅ Changing configuration (ENV variables, defaults, precedence) +- ✅ Modifying API endpoints (add to API Endpoints section) +- ✅ Updating database schema (add to Important fields section) +- ✅ Discovering system behaviors or quirks +- ✅ Implementing optimizations or enhancements +- ✅ Adding new integrations or dependencies +- ✅ Changing data flows or architecture +- ✅ Learning ANY lesson worth remembering + +**If you learned something valuable → Document it BEFORE pushing** +**If you solved a problem → Document the solution BEFORE pushing** +**If you discovered a pattern → Document the pattern BEFORE pushing** + +### The Correct Mindset: + +- **Documentation is NOT separate work** - It's part of completing the task +- **Documentation is NOT optional** - It's a requirement for "done" +- **Documentation is NOT an afterthought** - It's planned from the start +- **Every git commit is a learning opportunity** - Capture the knowledge + +### Examples of Commits Requiring Documentation: + +```bash +# Scenario 1: Bug fix reveals system behavior +git commit -m "fix: Correct P&L calculation for partial closes" +# → MUST document: Why averageExitPrice doesn't work, must use realizedPnL +# → MUST add to: Common Pitfalls section + +# Scenario 2: New feature with integration requirements +git commit -m "feat: Smart Entry Validation Queue system" +# → MUST document: How it works, when it triggers, integration points +# → MUST add to: Critical Components section + +# Scenario 3: Performance optimization reveals insight +git commit -m "perf: Adaptive leverage based on quality score" +# → MUST document: Quality thresholds, why tiers chosen, expected impact +# → MUST add to: Configuration System or relevant section + +# Scenario 4: Data analysis reveals filtering requirement +git commit -m "fix: Exclude manual trades from indicator analysis" +# → MUST document: signalSource field, SQL filtering patterns, why it matters +# → MUST add to: Important fields and Analysis patterns sections +``` + +### Red Flags That Documentation is Missing: + +- ❌ 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 +- ❌ You push code without updating copilot-instructions.md + +### Integration with Existing Sections: + +When documenting, update these sections as appropriate: +- **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 +- **Database Schema:** Add new tables/fields and their meaning +- **Architecture Overview:** Add new integrations or data flows + +### 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.** + +**This is the user's #1 priority. Make it yours too.** + **What qualifies as "valuable insights" requiring documentation:** 1. **System behaviors discovered** during implementation or debugging