Skip to content

DOCUMENTATION_INDEX.md

Latest commit

 

History

History
131 lines (95 loc) · 6.16 KB

DOCUMENTATION_INDEX.md

File metadata and controls

131 lines (95 loc) · 6.16 KB
Raw

Documentation Index for AI Assistants

🚨 MANDATORY: Read ALL files in docs/ COMPLETELY before touching any code.

🛑 CRITICAL WARNING: LEARNING PATH PROTECTION

⚠️ MOST DANGEROUS MISTAKE: Modifying learning path logic without permission

Files that can BREAK THE ENTIRE APP:

  • src/state/learningState.js - advanceLearningPath() function
  • src/modules/business/services/StateManager.js - Any progression logic
  • src/modules/business/services/QuestionGenerator.js - Question generation
  • ANY learning path progression logic

🚨 MANDATORY PROTOCOL: Before touching ANY of these files, you MUST ask explicit permission first. NO EXCEPTIONS.

📖 Required Reading Order (AI Assistants)

🔴 CRITICAL (Read First - Can Break App):

  1. LEARNING_PATH_PROTECTION.md - 🚨 CRITICAL protection protocols
  2. SYSTEMATIC_RESEARCH_METHODOLOGY.md - MANDATORY methodology for all work

🟡 MANDATORY (Core Protocols): 3. DOCUMENTATION_MAINTENANCE_PROTOCOL.md - MANDATORY with every change 4. URL_CONFIGURATION.md - CRITICAL app URL configuration 5. RESEARCH_TEMPLATE.md - Use for every investigation

🟢 ESSENTIAL (Development Knowledge): 6. DEVELOPMENT.md - Setup and architecture 7. DEPLOYMENT.md - Complete deployment guide and troubleshooting 8. TESTING.md - Testing and debugging procedures 9. CONTRIBUTING.md - Contribution requirements 10. LEARNING_PATH_COMPLETE.md - Learning path behavior 11. CURRENT_LEARNING_PATH_BEHAVIOR.md - Current implementation 12. HEADLESS_TEST_RESEARCH_FINDINGS.md - Methodology case study 13. RELEASE_FORMAT.md - Release procedures

✅ MANDATORY: Confirm Understanding

Before proceeding with ANY task, you MUST confirm:

  1. "I have read ALL 13 documentation files completely"
  2. "I understand that modifying learning path logic requires explicit permission"
  3. "I will use the systematic research methodology for all investigations"
  4. "I will update ALL required documentation types with every code change (research findings, code comments, user guides, and examples)"

⚠️ WARNING: Proceeding without this confirmation violates the protocol and risks breaking the app.

🚨 Common AI Assistant Failures (AVOID THESE)

❌ Most Dangerous Mistakes:

  1. Modifying learning path logic without permission → BREAKS ENTIRE APP
  2. Skipping systematic research → Fixes symptoms not root causes, creates new bugs
  3. Making assumptions instead of gathering evidence → Wrong solutions, wasted time
  4. Not updating documentation → CREATES DOCUMENTATION DEBT: Future developers waste hours re-researching solutions, examples break, knowledge is lost forever

❌ Investigation Shortcuts That Fail:

  • Jumping straight to code examination without reading docs
  • Assuming you understand the problem immediately
  • Making changes without understanding the full system
  • Testing only the immediate issue, not related functionality

✅ Success Pattern:

  1. Read ALL docs first → Complete understanding
  2. Use systematic methodology → Evidence-based solutions
  3. Follow protection protocols → No app breakage
  4. Update documentation → Knowledge preserved

⚡ Essential Protocols (Reference)

🔍 Investigation & Debugging

  • ALWAYS follow Systematic Research Methodology
  • NEVER make assumptions - gather evidence first
  • Use Research Template for every task
  • Apply ALL 5 phases: Problem decomposition → Evidence gathering → Analysis → Solution → Documentation

🛡️ Critical Protections

🧪 Testing Requirements

  • Run headless tests for all learning path changes
  • Follow Testing Guide procedures
  • Validate with evidence-based approach

📚 Technical Reference

File Contains Use When
STAGING_SETUP.md Staging environment setup and configuration Setting up or troubleshooting staging deployments
chord-variations.md Chord input reference Working with chord recognition
ACCIDENTALS_PAIRING_ANALYSIS.md Accidentals logic analysis Investigating accidentals behavior

🎯 Core Principles

  1. Evidence-Based Only - No assumptions, gather concrete evidence
  2. Documentation First - Update docs with every change
  3. Learning Path Protection - Critical app functionality, handle with extreme care
  4. Systematic Methodology - Follow all 5 phases for every task
  5. Test Validation - Verify changes with comprehensive testing

🎯 Self-Validation Checklist

Before making ANY changes, verify:

  • I have read all 13 docs completely
  • I understand which files are protected and why
  • I am using systematic research methodology
  • I am gathering evidence, not making assumptions
  • I have permission if touching learning path logic
  • I will update ALL required documentation: research findings, code comments, affected user guides, and examples
  • I understand that skipping documentation updates creates knowledge debt and confuses future developers
  • I will test thoroughly including regression testing

All work must follow the systematic research methodology. Documentation updates are mandatory with every code change. Always check docs/DEPLOYMENT.md for deployment procedures.