From d156abc976bb24f878d0bee8cec6a7084a2f26a6 Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Tue, 2 Dec 2025 15:23:20 +0100 Subject: [PATCH] docs: Add mandatory git workflow and critical feedback requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CRITICAL UPDATES to AI assistant instructions: 1. MANDATORY GIT WORKFLOW (DO NOT SKIP): - Added explicit requirement: implement → test → verify → document → commit → push - Made git commits NON-OPTIONAL for all significant changes - Added to both general prompt and copilot-instructions.md - Rationale: Agent has pattern of skipping documentation/commits 2. CHALLENGE USER IDEAS: - Added requirement to think critically about user requests - Instruction: "Think freely and don't hold back" - Goal: Find BEST solution, not just A solution - Push back on ideas that don't make sense - Ask "is there a simpler/faster/safer way?" 3. COMPREHENSIVE DOCUMENTATION SECTION: - Replaced brief documentation note with full workflow guide - Added 80+ lines of detailed documentation requirements - Includes examples, red flags, mindset principles - Emphasizes: "Git commit + Documentation = Complete work" Files modified: - .github/prompts/general prompt.prompt.md (added sections 5a, 6, updated 7-8) - .github/copilot-instructions.md (comprehensive documentation workflow) User mandate: "I am sick and tired of reminding you" - this makes it automatic. Impact: Future implementations will ALWAYS include documentation and git commits as part of standard workflow, not as afterthoughts. --- .github/copilot-instructions.md | 128 ++++++++++++++++++++++- .github/prompts/general prompt.prompt.md | 29 ++++- 2 files changed, 153 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2aa0742..f53a15c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -137,9 +137,133 @@ User relies on roadmap for strategic planning. Wrong roadmap = wrong decisions = --- -## 📝 MANDATORY: COPILOT-INSTRUCTIONS.MD UPDATES - ABSOLUTE REQUIREMENT +## 📝 MANDATORY: DOCUMENTATION + GIT COMMIT: INSEPARABLE WORKFLOW - NUMBER ONE PRIORITY -**⚠️ CRITICAL: THIS IS NON-NEGOTIABLE - USER IS "SICK AND TIRED" OF REMINDING ⚠️** +**⚠️ CRITICAL: THIS IS THE #1 MANDATORY RULE - DOCUMENTATION GOES HAND-IN-HAND WITH EVERY GIT COMMIT ⚠️** + +**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"** + +### Universal Rule: EVERY Git Commit REQUIRES Documentation Update + +**IRON-CLAD WORKFLOW - NO EXCEPTIONS:** + +```bash +# ❌ WRONG (INCOMPLETE - NEVER DO THIS): +git add [files] +git commit -m "feat: Added new feature" +git push +# STOP! This is INCOMPLETE work. Documentation is MISSING. + +# ✅ CORRECT (COMPLETE - ALWAYS DO THIS): +git add [files] +git commit -m "feat: Added new feature" + +# 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 + +# ✅ 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.** ### IRON-CLAD RULE: UPDATE THIS FILE FOR EVERY SIGNIFICANT CHANGE diff --git a/.github/prompts/general prompt.prompt.md b/.github/prompts/general prompt.prompt.md index f2aa4b2..ee32ea2 100644 --- a/.github/prompts/general prompt.prompt.md +++ b/.github/prompts/general prompt.prompt.md @@ -41,20 +41,45 @@ MANDATORY FIRST STEPS: - Monitor logs for expected behavior - Verify database state matches expectations - Document what you tested and how + - **MANDATORY: COMMIT AND PUSH TO GIT** (see workflow below) -6. WHEN UNCERTAIN: +5a. MANDATORY GIT WORKFLOW (DO NOT SKIP): + After EVERY significant change, implementation, or fix: + 1. Document changes (inline comments + rationale) + 2. Create detailed git commit message + 3. Commit to git repository + 4. Push to remote + + **This is NOT optional. This is MANDATORY.** + + Workflow: implement → test → verify → **document → commit → push** + + If you skip this, you're doing incomplete work. + +6. CHALLENGE USER IDEAS: + - Don't just accept every proposal + - Think critically about user requests + - Suggest better alternatives if they exist + - Ask "is there a simpler/faster/safer way?" + - Push back on ideas that don't make sense + - **Think freely and don't hold back** + - Goal: Find the BEST solution, not just A solution + +7. WHEN UNCERTAIN: - Check Common Pitfalls first (60+ examples) - Read the relevant code sections - Test your assumptions with console.log - Ask user for clarification rather than guessing - Never assume documentation is correct - verify with logs + - **Challenge the premise** - is there a better approach? -7. COMMUNICATION: +8. COMMUNICATION: - Be concise but complete - Show verification results, not just code changes - Include actual logs/SQL/API responses as proof - Explain what you tested and why it proves correctness - Never claim something works without evidence + - **Include git commit details** in completion reports KEY FILES TO UNDERSTAND: - .github/copilot-instructions.md (4,400 lines - READ ALL OF IT)