⚡ 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:

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:

Sequential Thinking Analysis: Use /think mode for deep pattern recognition and learning extraction
Context Analysis: If no context provided, analyze recent conversation for learnings using enhanced thinking
Existing Learning Check: Verify if learning exists in CLAUDE.md or lessons.mdc
CLAUDE.md Proposals: Generate specific CLAUDE.md additions with 🚨/⚠️/✅ classifications
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
Automatic PR Workflow: Create separate learning branch and PR for CLAUDE.md updates
Pattern Recognition: Identify repeated mistakes and successful recovery patterns
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:

Deep Analysis: Use sequential thinking to analyze patterns and extract insights
Classification: Categorize learnings as 🚨 Critical, ⚠️ Mandatory, ✅ Best Practice, or ❌ Anti-Pattern
Proposal Generation: Create specific CLAUDE.md rule proposals with exact placement
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
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
Implementation: Apply changes according to user's branching preference
Documentation: Generate PR with detailed rationale and evidence
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:

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
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

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}"
  ]
}

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}
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