Troubleshooting

This page provides solutions for common issues you might encounter when using the CursorRIPER Framework.

Framework Issues

Framework Not Loading

Symptoms:

• AI responses don't include mode declarations
• Commands like /research or /plan don't change modes
• No indication that the framework is active

Potential Causes and Solutions:

1. Missing or Misnamed Framework Files

   • Cause: Core framework files are missing or have incorrect extensions
   • Solution:

     # Check if files exist with proper .mdc extension
     ls -la .cursor/rules/
     
     # Rename any .md files to .mdc
     cd .cursor/rules/
     rename 's/\.md$/.mdc/' *.md
     

2. Incorrect File Locations

   • Cause: Files are not in the expected directory
   • Solution: Ensure core files are in .cursor/rules/ directory:
     • core.mdc
     • state.mdc
     • start-phase.mdc
     • riper-workflow.mdc
     • customization.mdc

3. Syntax Errors in MDC Files

   • Cause: MDC files contain syntax errors
   • Solution: Check for proper YAML frontmatter in MDC files:

     ---
     description: "CursorRIPER Framework - Core"
     globs: 
     alwaysApply: true
     ---
     

4. Cursor IDE Configuration

   • Cause: Cursor IDE settings blocking rules
   • Solution: Check Cursor settings:
     • Open Settings
     • Search for "rules" or "MDC"
     • Ensure rules are enabled

Commands Not Working

Symptoms:

• Commands like /research or /plan don't change modes
• AI acknowledges commands but doesn't change behavior

Potential Causes and Solutions:

1. Command Format Issues

   • Cause: Commands not formatted correctly
   • Solution: Use exact command format:
     • Slash commands: /research, /innovate, /plan, /execute, /review
     • Full commands: ENTER RESEARCH MODE, ENTER PLAN MODE, etc.

2. State File Corruption

   • Cause: state.mdc has invalid values
   • Solution: Reset state file:

     # Backup current state
     cp .cursor/rules/state.mdc .cursor/rules/state.mdc.bak
     
     # Create fresh state file
     cat > .cursor/rules/state.mdc << EOF
     ---
     description: "CursorRIPER Framework - State Management"
     globs: 
     alwaysApply: true
     ---
     
     # CursorRIPER Framework - State Management
     # Version 1.0.2
     
     PROJECT_PHASE: "UNINITIATED"
     RIPER_CURRENT_MODE: "NONE"
     START_PHASE_STATUS: "NOT_STARTED"
     START_PHASE_STEP: 0
     LAST_UPDATE: "$(date -Iseconds)"
     INITIALIZATION_DATE: ""
     FRAMEWORK_VERSION: "1.0.0"
     EOF
     

3. Invalid Project Phase

   • Cause: Current PROJECT_PHASE doesn't support RIPER modes
   • Solution: Check and correct PROJECT_PHASE in state.mdc:
     • Should be "DEVELOPMENT" or "MAINTENANCE" for RIPER commands
     • Run /start to complete initialization if needed

START Phase Issues

Symptoms:

• /start command doesn't initiate the START phase
• START phase gets stuck at a particular step

Potential Causes and Solutions:

1. Incomplete Prerequisites

   • Cause: Missing information needed for a step
   • Solution: Provide all requested information when prompted

2. START Phase File Issues

   • Cause: start-phase.mdc is missing or corrupted
   • Solution: Restore from backup or reinstall framework

3. Project Already Initialized

   • Cause: Project is already past initialization
   • Solution: To force re-initialization:

     CONFIRM RE-INITIALIZATION
     

     (Only use if absolutely necessary, as this may overwrite existing setup)

Memory Bank Issues

Missing Memory Files

Symptoms:

• References to missing memory files
• Errors about missing context
• AI responses lacking project-specific knowledge

Potential Causes and Solutions:

1. Memory Bank Not Initialized

   • Cause: START phase not completed
   • Solution: Run /start to complete initialization

2. Memory Files Deleted

   • Cause: Files accidentally deleted
   • Solution: Restore from backup:

     # Check for backups
     ls -la memory-bank/backups/
     
     # Restore from most recent backup
     cp memory-bank/backups/20250405_*/projectbrief.md memory-bank/
     

3. Incorrect Memory Bank Location

   • Cause: Memory files in wrong directory
   • Solution: Ensure files are in memory-bank/ directory in project root

Inconsistent Memory State

Symptoms:

• AI refers to features or decisions not actually made
• Memory files contain contradictory information
• Project state doesn't match memory content

Potential Causes and Solutions:

1. Outdated Memory Files

   • Cause: Files not updated after changes
   • Solution: Manually update memory files to reflect current state:

     Please update the memory bank to reflect the current project state.
     

2. Partial Updates

   • Cause: Some files updated but not others
   • Solution: Ensure all related files are updated consistently:
     • activeContext.md should match progress.md
     • systemPatterns.md should reflect current architecture

3. Backup Restoration Issues

   • Cause: Restoring some files from backups but not others
   • Solution: Always restore complete backup sets

Performance Issues

Symptoms:

• AI responses becoming slower
• Long delays when switching modes
• Memory files becoming unwieldy

Potential Causes and Solutions:

1. Oversized Memory Files

   • Cause: Files becoming too large with accumulated information
   • Solution: Archive old information and maintain focused content:

     # Create archives directory
     mkdir -p memory-bank/archives
     
     # Move older versions to archives
     cp memory-bank/progress.md memory-bank/archives/progress-$(date +%Y%m%d).md
     

     Then streamline current files

2. Too Many Memory Files

   • Cause: Custom memory files proliferating
   • Solution: Consolidate related information and maintain a clean structure

3. Memory Content Overload

   • Cause: Too much irrelevant information
   • Solution: Regular cleanup:

     Please help me clean up the memory bank to focus on current priorities.
     

Mode-Specific Issues

RESEARCH Mode Issues

Symptoms:

• AI makes suggestions instead of just gathering information
• Information gathering is incomplete

Potential Causes and Solutions:

1. Mode Confusion

   • Cause: AI not properly in RESEARCH mode
   • Solution: Explicitly reaffirm mode:

     /research
     Please stay strictly in RESEARCH mode and just help me understand [topic].
     

2. Ambiguous Requests

   • Cause: Requests that sound like asking for implementation
   • Solution: Frame questions as information gathering:

     # Instead of:
     How should I implement this feature?
     
     # Use:
     What are the key considerations I should understand about this feature?
     

PLAN Mode Issues

Symptoms:

• Plans lack sufficient detail
• AI skips asking clarifying questions
• Plans contain implementation code

Potential Causes and Solutions:

1. Insufficient Context

   • Cause: Not enough information provided for planning
   • Solution: Provide more context:

     /plan
     Create a detailed plan for implementing user authentication. The system needs to support both email/password and OAuth login, with JWT-based session management.
     

2. Impatience with Questions

   • Cause: Rushing through clarification phase
   • Solution: Adjust question count and thoroughly answer questions:

     # In customization.mdc:
     PLAN_QUESTION_COUNT: 7  # Increase for more thorough planning
     

3. Plan Detail Issues

   • Cause: Too vague or too detailed plans
   • Solution: Specify desired detail level:

     /plan
     Create a medium-detail plan for implementing the shopping cart feature. Focus on component structure and data flow, but we don't need individual function signatures.
     

EXECUTE Mode Issues

Symptoms:

• Implementation deviating from plan
• Steps skipped or implemented incorrectly
• Mode switching without authorization

Potential Causes and Solutions:

1. Incomplete Plans

   • Cause: Plan lacks sufficient detail for implementation
   • Solution: Return to PLAN mode:

     /plan
     Let's revise our plan to include more specific details about the database schema changes.
     

2. Unauthorized Mode Transitions

   • Cause: AI suggesting changes to plan during execution
   • Solution: Strict mode enforcement:

     /execute
     Please implement exactly according to the plan. If you find any issues, explicitly return to PLAN mode rather than modifying the plan.
     

3. Ambiguous Plan Items

   • Cause: Plan items open to interpretation
   • Solution: Seek clarification before continuing:

     /plan
     Let's clarify step 3 in our plan. When we say "implement authentication middleware", exactly what files need to be modified and how?
     

REVIEW Mode Issues

Symptoms:

• Missing deviation reports
• Incomplete review coverage
• Review overemphasizing minor issues

Potential Causes and Solutions:

1. Incomplete Implementation Reference

   • Cause: Review can't access original plan
   • Solution: Provide plan reference:

     /review
     Please compare the implementation against this plan: [paste plan]
     

2. Focus Issues

   • Cause: Review focusing on wrong aspects
   • Solution: Specify review focus:

     /review
     Focus on checking if the database schema changes match the plan. Ignore formatting differences.
     

3. Inconsistent Deviation Reporting

   • Cause: Unclear standards for what constitutes a deviation
   • Solution: Set deviation threshold:

     /review
     Please flag any functional deviations from the plan, but ignore minor formatting or variable name differences.
     

Custom Installation Issues

Multiple Project Confusion

Symptoms:

• AI confusing details between different projects
• Referencing wrong memory bank content

Potential Causes and Solutions:

1. Shared Framework Files

   • Cause: Using same framework files across projects
   • Solution: Ensure each project has its own framework files:

     # Copy fresh framework files
     mkdir -p /path/to/project/.cursor/rules/
     cp /path/to/CursorRIPER/src/.cursor/rules/* /path/to/project/.cursor/rules/
     

2. Project Identification Issues

   • Cause: Similar project names or structures
   • Solution: Clearly identify project in memory files:

     # Project Brief: [DISTINCTIVE_PROJECT_NAME]
     

Custom Mode Integration Issues

Symptoms:

• Custom modes not matching framework behavior
• Tool permissions inconsistent with mode requirements

Potential Causes and Solutions:

1. Mismatched Custom Mode Settings

   • Cause: Custom mode settings don't align with framework
   • Solution: Update custom mode instructions to match framework definitions

2. Tool Permission Issues

   • Cause: Required tools disabled in custom modes
   • Solution: Review and correct tool permissions for each mode

Recovery Procedures

Complete Framework Reset

If you need to completely reset the framework:

# Backup existing files
mkdir -p .cursor/backup
cp -r .cursor/rules/* .cursor/backup/
cp -r memory-bank .cursor/backup/memory-bank

# Delete existing framework files
rm .cursor/rules/core.mdc
rm .cursor/rules/state.mdc
rm .cursor/rules/start-phase.mdc
rm .cursor/rules/riper-workflow.mdc
rm .cursor/rules/customization.mdc

# Install fresh framework files
cp /path/to/CursorRIPER/src/.cursor/rules/* .cursor/rules/

# Start from scratch
/start

Memory Bank Recovery

To recover a corrupted memory bank:

# Check for backups
ls -la memory-bank/backups/

# If backups exist, restore
cp -r memory-bank/backups/YYYYMMDD_HHMMSS/* memory-bank/

# If no backups, recreate basic structure
mkdir -p memory-bank
touch memory-bank/projectbrief.md
touch memory-bank/systemPatterns.md
touch memory-bank/techContext.md
touch memory-bank/activeContext.md
touch memory-bank/progress.md

# Ask AI to regenerate content
/research
Please help me rebuild the memory bank with what you know about this project.

Partial Framework Recovery

If only certain components are malfunctioning:

# Identify problematic component
cat .cursor/rules/state.mdc  # Check current state

# Replace only that component
cp /path/to/CursorRIPER/src/.cursor/rules/component.mdc .cursor/rules/

# Reset state if needed
/research
Please help me reset the framework state to match the current project status.

Advanced Troubleshooting

Framework Debugging

For persistent issues, create a debug report:

# Create debug directory
mkdir -p debug-report

# Copy framework files (sanitize if needed)
cp .cursor/rules/*.mdc debug-report/

# Copy memory bank (sanitize if needed)
cp memory-bank/*.md debug-report/

# Create debug report
echo "CursorRIPER Debug Report" > debug-report/report.txt
echo "Date: $(date)" >> debug-report/report.txt
echo "Framework Version: $(grep FRAMEWORK_VERSION .cursor/rules/state.mdc | cut -d: -f2)" >> debug-report/report.txt
echo "Project Phase: $(grep PROJECT_PHASE .cursor/rules/state.mdc | cut -d: -f2)" >> debug-report/report.txt
echo "Current Mode: $(grep RIPER_CURRENT_MODE .cursor/rules/state.mdc | cut -d: -f2)" >> debug-report/report.txt
echo "Issue Description: [Add your description here]" >> debug-report/report.txt

Framework Verification

To verify framework integrity:

# Check file presence
for file in core.mdc state.mdc start-phase.mdc riper-workflow.mdc customization.mdc; do
  if [ -f ".cursor/rules/$file" ]; then
    echo "✓ $file exists"
  else
    echo "✗ $file missing"
  fi
done

# Check memory bank
for file in projectbrief.md systemPatterns.md techContext.md activeContext.md progress.md; do
  if [ -f "memory-bank/$file" ]; then
    echo "✓ $file exists"
  else
    echo "✗ $file missing"
  fi
done

# Check state consistency
phase=$(grep PROJECT_PHASE .cursor/rules/state.mdc | cut -d: -f2 | tr -d ' "')
mode=$(grep RIPER_CURRENT_MODE .cursor/rules/state.mdc | cut -d: -f2 | tr -d ' "')
echo "Current phase: $phase"
echo "Current mode: $mode"

# Verify phase-mode compatibility
if [ "$phase" = "DEVELOPMENT" ] || [ "$phase" = "MAINTENANCE" ]; then
  echo "✓ Phase supports RIPER modes"
else
  echo "✗ Phase does not support RIPER modes"
fi

Framework Logs

To create a simple framework activity log:

# Create log directory
mkdir -p .cursor/logs

# Create log entry function
log_framework_activity() {
  echo "$(date -Iseconds) - $1" >> .cursor/logs/framework-activity.log
}

# Log mode transition
log_framework_activity "Mode transition: $previous_mode -> $new_mode"

# Log plan creation
log_framework_activity "Plan created: $plan_description"

# Log execution
log_framework_activity "Executed steps: $steps_executed"

You can then create a simple log viewer script:

#!/bin/bash
# view-framework-log.sh

if [ -f .cursor/logs/framework-activity.log ]; then
  cat .cursor/logs/framework-activity.log | less
else
  echo "No framework activity log found."
fi

Common Error Messages

"Framework state inconsistency detected"

Cause: State file contains conflicting or invalid values.

Solution:

1. Check state.mdc for mismatched values
2. Ensure PROJECT_PHASE matches RIPER_CURRENT_MODE
3. Reset state if necessary (see "State File Corruption" above)

"Memory bank file not found"

Cause: Required memory file is missing.

Solution:

1. Check if file exists in memory-bank directory
2. Restore from backup if available
3. Create missing file with appropriate template

"This operation is not permitted in [MODE] mode"

Cause: Attempting action not allowed in current mode.

Solution:

1. Switch to appropriate mode for the action
2. Follow the RIPER workflow sequence

"Cannot transition to EXECUTE mode without approved plan"

Cause: Attempting to enter EXECUTE mode without completing PLAN.

Solution:

1. Return to PLAN mode
2. Create and get approval for detailed plan
3. Then transition to EXECUTE

"Memory bank requires initialization"

Cause: Attempting operations before completing START phase.

Solution:

1. Run /start command
2. Complete all START phase steps
3. Then try operation again

Preventative Measures

To avoid common issues, follow these best practices:

1. Regular Backups

   # Create backup script
   cat > backup-memory.sh << 'EOF'
   #!/bin/bash
   BACKUP_DIR="memory-bank/backups/$(date +%Y%m%d_%H%M%S)"
   mkdir -p "$BACKUP_DIR"
   cp memory-bank/*.md "$BACKUP_DIR/"
   echo "Memory bank backed up to $BACKUP_DIR"
   EOF
   
   chmod +x backup-memory.sh
   

2. State Validation

   • Periodically check state.mdc for consistency
   • Ensure project phase and mode align with actual status

3. Memory Hygiene

   • Regularly clean up and organize memory files
   • Archive outdated information
   • Keep content focused and relevant

4. Framework Updates

   • Check for framework updates periodically
   • Apply updates consistently across all components

5. Documentation Practices

   • Document framework modifications
   • Keep track of customizations
   • Note any workarounds implemented

Getting Help

If you encounter persistent issues:

1. Gather framework debug information (see Framework Debugging)
2. Check GitHub repository for known issues
3. Post in discussions with clear problem description
4. Include:
   • Framework version
   • Issue symptoms
   • Steps to reproduce
   • Any error messages
   • Any modifications to standard framework

---

CursorRIPER: Adaptive development, persistent intelligence.