⚡ EXECUTION INSTRUCTIONS FOR CLAUDE

When this command is invoked, YOU (Claude) must execute these steps immediately: This is NOT documentation - these are COMMANDS to execute right now. Use TodoWrite to track progress through multi-phase workflows.

🚨 EXECUTION WORKFLOW

Phase 1: Execute Documented Workflow

Action Steps:

1. Review the reference documentation below and execute the detailed steps sequentially.

📋 REFERENCE DOCUMENTATION

/learn Command

Purpose: The unified learning command that captures and documents learnings with Memory MCP integration for persistent knowledge storage

Usage: /learn [optional: specific learning or context]

Note: This is the single, unified /learn command. All learning functionality is consolidated here with Memory MCP integration as the default.

Enhanced Behavior:

1. Sequential Thinking Analysis: Use /think mode for deep pattern recognition and learning extraction
2. Context Analysis: If no context provided, analyze recent conversation for learnings using enhanced thinking
3. Existing Learning Check: Verify if learning exists in CLAUDE.md or lessons.mdc
4. CLAUDE.md Proposals: Generate specific CLAUDE.md additions with 🚨/⚠️/✅ classifications
5. Memory MCP Integration with Query Optimization: Persist learnings to knowledge graph with enhanced search effectiveness
   • Universal Composition: Use /memory search for automatic query optimization and improved learning pattern discovery
   • Smart Search Strategy: Leverage /memory command's automatic compound query transformation
   • Entity Creation: Use /memory learn for structured learning entity creation with relationship discovery
   • Performance Enhancement: Improve search success from ~30% to 70%+ through intelligent query transformation
6. Automatic PR Workflow: Create separate learning branch and PR for CLAUDE.md updates
7. Pattern Recognition: Identify repeated mistakes and successful recovery patterns
8. Auto-Learning Integration: Support automatic triggering from other commands

Examples:

• /learn - Analyze recent mistakes/corrections
• /learn always use source venv/bin/activate - Add specific learning
• /learn playwright is installed, stop saying it isn't - Correct misconception

Auto-Learning Categories:

• Commands: Correct command usage patterns
• Testing: Test execution methods
• Tools: Available tools and their proper usage
• Misconceptions: Things Claude wrongly assumes
• Patterns: Repeated mistakes to avoid

Enhanced Workflow:

1. Deep Analysis: Use sequential thinking to analyze patterns and extract insights
2. Classification: Categorize learnings as 🚨 Critical, ⚠️ Mandatory, ✅ Best Practice, or ❌ Anti-Pattern
3. Proposal Generation: Create specific CLAUDE.md rule proposals with exact placement
4. Memory MCP Integration: Store learnings persistently in knowledge graph
   • Version Check: Verify backup script is current using memory/check_backup_version.sh
   • Entity Creation: Create learning entities with proper schema
   • Duplicate Detection: Search existing graph to prevent redundant entries
   • Relation Building: Connect related learnings and patterns
   • Observation Addition: Add learning content to existing entities when appropriate
5. Branch Choice: Offer user choice between:
   • Current PR: Include learning changes in existing work (related context)
   • Clean Branch: Create independent learning PR from fresh main branch
6. Implementation: Apply changes according to user's branching preference
7. Documentation: Generate PR with detailed rationale and evidence
8. Branch Management: Return to original context or manage clean branch appropriately

Auto-Trigger Scenarios:

• Merge Intentions: Triggered by "ready to merge", "merge this", "ship it"
• Failure Recovery: After 3+ failed attempts followed by success
• Integration: Automatically called by /integrate command
• Manual Request: Direct /learn invocation

Learning Categories:

• 🚨 Critical Rules: Patterns that prevent major failures
• ⚠️ Mandatory Processes: Required workflow steps discovered
• ✅ Best Practices: Successful patterns to follow
• ❌ Anti-Patterns: Patterns to avoid based on failures

Updates & Integration:

• CLAUDE.md for critical rules (via automatic PR)
• .cursor/rules/lessons.mdc for detailed technical learnings
• .claude/learnings.md for categorized knowledge base
• Memory MCP Knowledge Graph: Persistent entities and relations across conversations
• Failure/success pattern tracking for auto-triggers
• Integration with other slash commands (/integrate, merge detection)

Enhanced Memory MCP Entity Schema:

High-Quality Entity Types:

• technical_learning - Specific technical solutions with code/errors
• implementation_pattern - Successful code patterns with reusable details
• debug_session - Complete debugging journeys with root causes
• fix_implementation - Documented fixes with validation steps
• workflow_insight - Process improvements with measurable outcomes
• architecture_decision - Design choices with rationale and trade-offs
• user_preference_pattern - User interaction patterns with optimization

Enhanced Observations Format:

• Context: Specific situation with timestamp and circumstances
• Technical Detail: Exact errors, code snippets, file locations (file:line)
• Solution Applied: Specific steps taken with measurable results
• References: PR links, commits, files, documentation URLs
• Reusable Pattern: How learning applies to other contexts
• Verification: How solution was confirmed (test results, metrics)
• Related Issues: Connected problems this addresses

Quality Requirements:

• ✅ Specific file paths with line numbers ($PROJECT_ROOT/auth.py:45)
• ✅ Exact error messages or code snippets
• ✅ Actionable implementation steps
• ✅ References to PRs, commits, or external resources
• ✅ Measurable outcomes (test counts, performance metrics)
• ✅ Canonical entity names for disambiguation

Enhanced Relations: fixes, implemented_in, tested_by, caused_by, prevents, optimizes, supersedes, requires

Enhanced Memory MCP Implementation Steps:

1. Enhanced Search & Context:

   • Extract specific technical terms (file names, error messages, PR numbers)
   • Search: /memory search "technical terms" - Use universal composition for optimized search
   • Log results only if found or errors
   • Integrate found context naturally into response

2. Quality-Enhanced Entity Creation:

   • Use high-quality entity patterns with specific technical details
   • Include canonical naming: {system}_{issue}_{timestamp} format
   • Ensure actionable observations with file:line references
   • Add measurable outcomes and verification steps

3. Structured Observation Capture:

   {
     "name": "{canonical_identifier}",
     "entityType": "{technical_learning|implementation_pattern|debug_session}",
     "observations": [
       "Context: {specific situation with timestamp}",
       "Technical Detail: {exact error/solution/code with file:line}",
       "Solution Applied: {specific steps taken}",
       "Verification: {test results, metrics, confirmation}",
       "References: {PR URLs, commits, files}",
       "Reusable Pattern: {how to apply elsewhere}"
     ]
   }
   

4. Enhanced Relation Building:

   • Link fixes to original problems: {fix} fixes {problem}
   • Connect implementations to locations: {solution} implemented_in {file}
   • Associate patterns with users: {pattern} preferred_by {user}
   • Build implementation genealogies: {new_pattern} supersedes {old_pattern}

5. Quality Validation:

   • ✅ Contains specific technical details (error messages, file paths)
   • ✅ Includes actionable information (reproduction steps, fixes)
   • ✅ References external artifacts (PRs, commits, documentation)
   • ✅ Uses canonical entity names
   • ✅ Provides measurable outcomes
   • ✅ Links to related memories explicitly

Integration Function Calls:

# Check backup script version consistency

memory/check_backup_version.sh || echo "Warning: Backup script version mismatch"

# Search for existing similar learnings (with error handling)

try:
    /memory search "[key terms from learning]"
except Exception as e:
    log_error("Memory MCP search failed: " + str(e))
    fallback_to_local_only_mode()

# Create enhanced entity with high-quality patterns (with error handling)

try:
    mcp__memory-server__create_entities([{
      "name": "{system}_{issue_type}_{timestamp}",  # Canonical naming
      "entityType": "{technical_learning|implementation_pattern|debug_session|workflow_insight}",  # Select appropriate type
      "observations": [
        "Context: {specific situation with timestamp and circumstances}",
        "Technical Detail: {exact error message or code with file:line}",
        "Root Cause: {identified cause with evidence}",
        "Solution Applied: {specific implementation steps taken}",
        "Code Changes: {file paths and line numbers modified}",
        "Verification: {test results, performance metrics, confirmation}",
        "References: {PR URLs, commit hashes, related documentation}",
        "Reusable Pattern: {how this solution applies to other contexts}",
        "Classification: [🚨|⚠️|✅|❌] {reason for classification}"
      ]
    }])
except Exception as e:
    log_error("Memory MCP entity creation failed: " + str(e))
    notify_user("Learning saved locally only - Memory MCP unavailable")

# Build relations to related concepts (with error handling)

try:
    mcp__memory-server__create_relations([{
      "from": "[learning-name]",
      "to": "[related-concept]",
      "relationType": "[relates_to|caused_by|prevents|applies_to]"
    }])
except Exception as e:
    log_error("Memory MCP relation creation failed: " + str(e))
    # Relations are optional - continue without them

Error Handling Strategy:

• Graceful Degradation: Continue with local file updates if Memory MCP fails
• User Notification: Inform user when Memory MCP unavailable but learning saved locally
• Fallback Mode: Local-only operation when Memory MCP completely unavailable
• Robust Operation: Never let Memory MCP failures prevent learning capture