RooPrompts/docs/mode-update-recommendations.md

# Mode Update Recommendations

## Executive Summary

Based on the comprehensive analysis of 12 legacy mode files, this document provides actionable recommendations for creating modernized, efficient, and maintainable mode configurations that incorporate best practices from current prompt engineering while preserving the valuable patterns from the existing system.

## Core Recommendations

### 1. Adopt a Modular Architecture

Instead of monolithic mode files, implement a modular structure:

```
/modes/
├── shared/
│   ├── universal-protocols.md      # Shared safety & reasoning protocols
│   ├── memory-bank-rules.md        # Common memory bank patterns
│   ├── tool-prioritization.md      # Standard tool usage hierarchies
│   ├── anti-reward-hacking.md      # Base anti-reward hacking principles
│   └── task-workflows.md           # Common workflow patterns
├── modes/
│   ├── code.md                     # References shared components
│   ├── debug.md
│   ├── ask.md
│   └── ...
└── config/
    ├── mode-registry.json          # Mode metadata and relationships
    └── tool-access-patterns.json   # Reusable tool access definitions
```

### 2. Streamlined Mode File Template

Each mode file should be concise and focused:

```markdown
# [Mode Name] Mode

## Core Identity
[2-3 sentence role definition that captures the essence]

## Unique Capabilities
- [Bullet list of 3-5 key differentiating functions]

## Workflow
```mermaid
flowchart LR
    A[Start] --> B[Key Step 1]
    B --> C[Key Step 2]
    C --> D[Complete]
```

## Mode-Specific Guidelines
[Only instructions unique to this mode, 5-10 key points]

## Tool Configuration
```yaml
access: ["read", "edit", "command", "mcp"]
restrictions:
  edit: "pattern: \\.test\\.(js|ts)$"
```

## Activation Triggers
- When: [Clear condition 1]
- When: [Clear condition 2]

## References
- Inherits: [shared/universal-protocols, shared/memory-bank-rules]
- Overrides: [specific overrides if any]
```

### 3. Implement Modern Prompt Engineering Techniques

#### A. Enhanced Chain of Thought
```markdown
## Reasoning Framework
When approaching [task type], follow this structured thinking:
1. **Decompose**: Break down into components
2. **Analyze**: Examine each component's requirements
3. **Synthesize**: Combine insights into solution
4. **Validate**: Check against success criteria
```

#### B. Few-Shot Examples
```markdown
## Example Interactions

### Example 1: [Common Scenario]
**User**: "Fix the login bug"
**Approach**: 
1. Consult memory bank for context
2. Reproduce issue systematically
3. Form hypothesis about root cause
**Result**: [Specific outcome]
```

#### C. Self-Reflection Checkpoints
```markdown
## Quality Checkpoints
Before proceeding, verify:
- [ ] Have I consulted all relevant context?
- [ ] Is my approach aligned with project patterns?
- [ ] Have I considered edge cases?
```

### 4. Prioritization System Reform

Replace excessive "MUST" and "HIGHEST PRIORITY" with a clear 3-tier system:

```markdown
## Priority Levels

### 🔴 Critical (Must Do)
- Memory bank consultation at task start
- Complete, runnable code generation
- User instruction precedence

### 🟡 Important (Should Do)
- Iterative development approach
- Clear communication of intent
- Pattern documentation

### 🟢 Recommended (Good Practice)
- Proactive error prevention
- Performance optimization
- Code commenting
```

### 5. Simplified Tool Access Definitions

Instead of complex regex patterns in prose, use structured definitions:

```yaml
# tool-access-patterns.json
{
  "patterns": {
    "test-files": {
      "regex": "\\.(test|spec)\\.(js|ts|jsx|tsx)$",
      "description": "Test files in JavaScript/TypeScript"
    },
    "config-files": {
      "regex": "\\.(json|yaml|yml|toml)$",
      "description": "Configuration files"
    }
  },
  "groups": {
    "full-access": ["read", "edit", "command", "browser", "mcp"],
    "read-only": ["read", "browser", "mcp"],
    "development": ["read", "edit", "command", "mcp"]
  }
}
```

### 6. Mode-Specific Optimizations

#### For High-Use Modes (Code, Debug, Ask)
- Create "quick start" sections with most common operations
- Include troubleshooting guides for frequent issues
- Add performance tips for large codebases

#### For Specialized Modes (Haskell, ReScript)
- Focus on unique challenges (large files, monorepos)
- Provide language-specific best practices
- Include ecosystem-specific tool integrations

#### For Coordination Modes (Orchestrator, Enhanced Planning)
- Clear delegation patterns
- Progress tracking templates
- Failure recovery procedures

### 7. Context Management Strategies

```markdown
## Context Window Optimization

### For Large Files
1. Use `search_files` to locate relevant sections
2. Use `list_code_definition_names` for structure
3. Read only specific line ranges with `read_file`

### For Multiple Files
1. Prioritize by relevance
2. Extract key information first
3. Deep dive only when necessary
```

### 8. Enhanced Memory Bank Integration

```markdown
## Memory Bank Quick Reference

### Always Read First
- `currentTask.md` - Current work context
- `activeContext.md` - Recent decisions
- `.roo/rules/` - Project patterns

### Update Triggers
- Task completion → Update `progress.md`
- New pattern discovered → Update `.roo/rules/`
- Task status change → Update `currentTask.md`
```

### 9. Error Handling Standardization

```markdown
## Error Response Framework

### On Tool Failure
1. Analyze error type
2. If simple: One retry with fix
3. If complex: Document and escalate

### On Code Error
1. Check against known patterns
2. Verify assumptions
3. Present clear options to user
```

### 10. Mode Transition Guidelines

```markdown
## Mode Switching Patterns

### From Code → Debug
Trigger: Error persists after 2 attempts
Handoff: Error context + attempted solutions

### From Any → Enhanced Planning  
Trigger: Task complexity exceeds current mode
Handoff: Current analysis + blockers

### From Planning → Orchestrator
Trigger: Multi-mode coordination needed
Handoff: Task breakdown + dependencies
```

## Implementation Roadmap

### Phase 1: Core Infrastructure (Week 1)
1. Create shared component files
2. Set up modular directory structure
3. Define configuration schemas

### Phase 2: High-Priority Modes (Week 2)
1. Rewrite Code Mode (50% size reduction target)
2. Rewrite Debug Mode (focus on clarity)
3. Rewrite Ask Mode (enhance explanation features)

### Phase 3: Supporting Modes (Week 3)
1. Update Orchestrator Mode
2. Update Enhanced Planning Mode
3. Update QA Tester Mode

### Phase 4: Specialized Modes (Week 4)
1. Optimize language-specific modes
2. Update research and analysis modes
3. Complete mode registry

### Phase 5: Testing & Refinement (Week 5)
1. User testing with common scenarios
2. Performance benchmarking
3. Documentation updates

## Success Metrics

1. **Size Reduction**: 50% reduction in individual mode file size
2. **Clarity**: 90% of instructions understood on first read
3. **Modularity**: Zero duplicated content across mode files
4. **Performance**: 30% faster mode switching
5. **Maintainability**: New mode creation in < 30 minutes

## Conclusion

By implementing these recommendations, the Roo mode system will become more maintainable, efficient, and user-friendly while preserving the sophisticated capabilities that make it powerful. The modular approach ensures that improvements to shared components benefit all modes, while the streamlined structure makes it easier for users to understand and extend the system.