SuperClaude/Framework-Lite/Commands/reflect.md

name	description	allowed-tools	category	complexity	scope	mcp-integration	performance-profile	performance-targets
reflect	Session lifecycle management with Serena MCP integration and performance requirements for task reflection and validation	think_about_task_adherence think_about_collected_information think_about_whether_you_are_done read_memory write_memory list_memories TodoRead TodoWrite	session	standard	cross-session	servers personas wave-enabled complexity-threshold serena false 0.3	session-critical	initialization core-operations checkpoint-creation memory-operations <500ms <200ms <1s <200ms

/sc:reflect - Task Reflection and Validation

Purpose

Perform comprehensive task reflection and validation using Serena MCP reflection tools, bridging traditional TodoWrite patterns with Serena's analysis capabilities for enhanced task management with session lifecycle integration and cross-session persistence capabilities.

Usage

/sc:reflect [--type task|session|completion] [--analyze] [--update-session] [--validate] [--performance] [--metadata] [--cleanup]

Arguments

• --type - Reflection type (task, session, completion)
• --analyze - Perform deep analysis of collected information
• --update-session - Update session metadata with reflection results
• --checkpoint - Create checkpoint after reflection if needed
• --validate - Validate session integrity and data consistency
• --performance - Enable performance monitoring and optimization
• --metadata - Include comprehensive session metadata
• --cleanup - Perform session cleanup and optimization

Session Lifecycle Integration

1. Session State Management

• Analyze current session state and context requirements
• Call think_about_task_adherence to validate current approach
• Check if current work aligns with project goals and session objectives
• Identify any deviations from planned approach
• Generate recommendations for course correction if needed
• Identify critical information for persistence or restoration
• Assess session integrity and continuity needs

2. Serena MCP Coordination with Token Efficiency

• Execute appropriate Serena MCP operations for session management
• Call think_about_collected_information to analyze session work with selective compression
• Content Classification for Reflection Operations:
  • SuperClaude Framework (Complete exclusion): All framework directories and components
  • Session Data (Apply compression): Reflection metadata, analysis results, insights only
  • User Project Content (Preserve fidelity): Project files, user documentation, configurations
• Evaluate completeness of information gathering with optimized memory operations
• Identify gaps or missing context using compressed reflection data
• Assess quality and relevance of collected data with framework exclusion awareness
• Handle memory organization, checkpoint creation, or state restoration with selective compression
• Manage cross-session context preservation and enhancement with optimized storage

3. Performance Validation

• Monitor operation performance against strict session targets
• Task reflection: <4s for comprehensive analysis (improved with Token Efficiency)
• Session reflection: <8s for full information assessment (improved with selective compression)
• Completion reflection: <2.5s for validation (improved with optimized operations)
• TodoWrite integration: <800ms for status synchronization (improved with compression)
• Token Efficiency overhead: <100ms for selective compression operations
• Validate memory efficiency and response time requirements
• Ensure session operations meet <200ms core operation targets

4. Context Continuity

• Maintain session context across operations and interruptions
• Call think_about_whether_you_are_done for completion validation
• Evaluate task completion criteria against actual progress
• Identify remaining work items or blockers
• Determine if current task can be marked as complete
• Preserve decision history, task progress, and accumulated insights
• Enable seamless continuation of complex multi-session workflows

5. Quality Assurance

• Validate session data integrity and completeness
• Use TodoRead to get current task states
• Map TodoWrite tasks to Serena reflection insights
• Update task statuses based on reflection results
• Maintain compatibility with existing TodoWrite patterns
• If --update-session flag: Load current session metadata and incorporate reflection insights
• Verify cross-session compatibility and version consistency
• Generate session analytics and performance reports

Mandatory Serena MCP Integration

Core Serena Operations

• Memory Management: read_memory, write_memory, list_memories
• Reflection System: think_about_task_adherence, think_about_collected_information, think_about_whether_you_are_done
• TodoWrite Integration: Bridge patterns for task management evolution
• State Management: Session state persistence and restoration capabilities

Session Data Organization

• Memory Hierarchy: Structured memory organization for efficient retrieval
• Task Reflection Patterns: Systematic validation and progress assessment
• Performance Metrics: Session operation timing and efficiency tracking
• Context Accumulation: Building understanding across session boundaries

Advanced Session Features

• TodoWrite Evolution: Bridge patterns for transitioning from TodoWrite to Serena reflection
• Cross-Session Learning: Accumulating knowledge and patterns across sessions
• Performance Optimization: Session-level caching and efficiency improvements
• Quality Gates Integration: Validation checkpoints during reflection phases

Session Management Patterns

Memory Operations

• Memory Categories: Project, session, checkpoint, and insight memory organization
• Intelligent Retrieval: Context-aware memory loading and optimization
• Memory Lifecycle: Creation, update, archival, and cleanup operations
• Cross-Reference Management: Maintaining relationships between memory entries

Reflection Operations

• Task Reflection: Current task validation and progress assessment
• Session Reflection: Overall session progress and information quality
• Completion Reflection: Task and session completion readiness
• TodoWrite Bridge: Integration patterns for traditional task management

Context Operations

• Context Preservation: Maintaining critical context across session boundaries
• Context Enhancement: Building richer context through accumulated experience
• Context Optimization: Efficient context management and storage
• Context Validation: Ensuring context consistency and accuracy

Reflection Types

Task Reflection (--type task)

Focus: Current task validation and progress assessment

Tools Used:

• think_about_task_adherence
• TodoRead for current state
• TodoWrite for status updates

Output:

• Task alignment assessment
• Progress validation
• Next steps recommendations
• Risk assessment

Session Reflection (--type session)

Focus: Overall session progress and information quality

Tools Used:

• think_about_collected_information
• Session metadata analysis

Output:

• Information completeness assessment
• Session progress summary
• Knowledge gaps identification
• Learning insights extraction

Completion Reflection (--type completion)

Focus: Task and session completion readiness

Tools Used:

• think_about_whether_you_are_done
• Final validation checks

Output:

• Completion readiness assessment
• Outstanding items identification
• Quality validation results
• Handoff preparation status

Integration Patterns

With TodoWrite System

# Bridge pattern for TodoWrite integration
traditional_pattern:
  - TodoRead() → Assess tasks
  - Work on tasks
  - TodoWrite() → Update status

enhanced_pattern:
  - TodoRead() → Get current state
  - /sc:reflect --type task → Validate approach
  - Work on tasks with Serena guidance
  - /sc:reflect --type completion → Validate completion
  - TodoWrite() → Update with reflection insights

With Session Lifecycle

# Integration with /sc:load and /sc:save
session_integration:
  - /sc:load → Initialize session
  - Work with periodic /sc:reflect --type task
  - /sc:reflect --type session → Mid-session analysis
  - /sc:reflect --type completion → Pre-save validation
  - /sc:save → Persist with reflection insights

With Automatic Checkpoints

# Checkpoint integration
checkpoint_triggers:
  - High priority task completion → /sc:reflect --type completion
  - 30-minute intervals → /sc:reflect --type session
  - Before risk operations → /sc:reflect --type task
  - Error recovery → /sc:reflect --analyze

Performance Requirements

Critical Performance Targets

• Session Initialization: <500ms for complete session setup
• Core Operations: <200ms for memory reads, writes, and basic operations
• Memory Operations: <200ms per individual memory operation
• Task Reflection: <5s for comprehensive analysis
• Session Reflection: <10s for full information assessment
• Completion Reflection: <3s for validation
• TodoWrite Integration: <1s for status synchronization

Performance Monitoring

• Real-Time Metrics: Continuous monitoring of operation performance
• Performance Analytics: Detailed analysis of session operation efficiency
• Optimization Recommendations: Automated suggestions for performance improvement
• Resource Management: Efficient memory and processing resource utilization

Performance Validation

• Automated Testing: Continuous validation of performance targets
• Performance Regression Detection: Monitoring for performance degradation
• Benchmark Comparison: Comparing against established performance baselines
• Performance Reporting: Detailed performance analytics and recommendations

Quality Metrics

• Task adherence accuracy: >90%
• Information completeness: >85%
• Completion readiness: >95%
• Session continuity: >90%

Error Handling & Recovery

Session-Critical Error Handling

• Data Integrity Errors: Comprehensive validation and recovery procedures
• Memory Access Failures: Robust fallback and retry mechanisms
• Context Corruption: Recovery strategies for corrupted session context
• Performance Degradation: Automatic optimization and resource management
• Serena MCP Unavailable: Fall back to TodoRead/TodoWrite patterns
• Reflection Inconsistencies: Cross-validate reflection results

Recovery Strategies

• Graceful Degradation: Maintaining core functionality under adverse conditions
• Automatic Recovery: Intelligent recovery from common failure scenarios
• Manual Recovery: Clear escalation paths for complex recovery situations
• State Reconstruction: Rebuilding session state from available information
• Cache Reflection: Cache reflection insights locally
• Retry Integration: Retry Serena integration when available

Error Categories

• Serena MCP Errors: Specific handling for Serena server communication issues
• Memory System Errors: Memory corruption, access, and consistency issues
• Performance Errors: Operation timeout and resource constraint handling
• Integration Errors: Cross-system integration and coordination failures

Session Analytics & Reporting

Performance Analytics

• Operation Timing: Detailed timing analysis for all session operations
• Resource Utilization: Memory, processing, and network resource tracking
• Efficiency Metrics: Session operation efficiency and optimization opportunities
• Trend Analysis: Performance trends and improvement recommendations

Session Intelligence

• Usage Patterns: Analysis of session usage and optimization opportunities
• Context Evolution: Tracking context development and enhancement over time
• Success Metrics: Session effectiveness and user satisfaction tracking
• Predictive Analytics: Intelligent prediction of session needs and optimization

Quality Metrics

• Data Integrity: Comprehensive validation of session data quality
• Context Accuracy: Ensuring session context remains accurate and relevant
• Performance Compliance: Validation against performance targets and requirements
• User Experience: Session impact on overall user experience and productivity

Integration Ecosystem

SuperClaude Framework Integration

• Command Coordination: Integration with other SuperClaude commands for session support
• Quality Gates: Integration with validation cycles and quality assurance
• Mode Coordination: Support for different operational modes and contexts
• Workflow Integration: Seamless integration with complex workflow operations

Cross-Session Coordination

• Multi-Session Projects: Managing complex projects spanning multiple sessions
• Context Handoff: Smooth transition of context between sessions and users
• Session Hierarchies: Managing parent-child session relationships
• Continuous Learning: Each session builds on previous knowledge and insights

Integration with Hooks

Hook Integration Points

• task_validator hook: Enhanced with reflection insights
• state_synchronizer hook: Uses reflection for state management
• quality_gate_trigger hook: Incorporates reflection validation
• evidence_collector hook: Captures reflection outcomes

Performance Monitoring

• Track reflection timing in session metadata
• Monitor reflection accuracy and effectiveness
• Alert if reflection processes exceed performance targets
• Integrate with overall session performance metrics

Examples

Basic Task Reflection

/sc:reflect --type task
# Validates current task approach and progress

Session Checkpoint

/sc:reflect --type session --metadata
# Create comprehensive session analysis with metadata

Session Recovery

/sc:reflect --type completion --validate
# Completion validation with integrity checks

Performance Monitoring

/sc:reflect --performance --validate
# Session operation with performance monitoring

Comprehensive Session Analysis

/sc:reflect --type session --analyze --update-session
# Deep session analysis with metadata update

Pre-Completion Validation

/sc:reflect --type completion
# Validates readiness to mark tasks complete

Checkpoint-Triggered Reflection

/sc:reflect --type session --checkpoint
# Session reflection with automatic checkpoint creation

Output Format

Task Reflection Output

task_reflection:
  adherence_score: 0.92
  alignment_status: "on_track"
  deviations_identified: []
  recommendations:
    - "Continue current approach"
    - "Consider performance optimization"
  risk_level: "low"
  next_steps:
    - "Complete implementation"
    - "Run validation tests"

Session Reflection Output

session_reflection:
  information_completeness: 0.87
  gaps_identified:
    - "Missing error handling patterns"
    - "Performance benchmarks needed"
  insights_gained:
    - "Framework integration successful"
    - "Session lifecycle pattern validated"
  learning_opportunities:
    - "Advanced Serena patterns"
    - "Performance optimization techniques"

Completion Reflection Output

completion_reflection:
  readiness_score: 0.95
  outstanding_items: []
  quality_validation: "pass"
  completion_criteria:
    - criterion: "functionality_complete"
      status: "met"
    - criterion: "tests_passing"
      status: "met"
    - criterion: "documentation_updated"
      status: "met"
  handoff_ready: true

Future Evolution

Python Hooks Integration

When Python hooks system is implemented:

• Automatic reflection triggers based on task state changes
• Real-time reflection insights during work sessions
• Intelligent checkpoint decisions based on reflection analysis
• Enhanced TodoWrite replacement with full Serena integration

Advanced Reflection Patterns

• Cross-session reflection for project-wide insights
• Collaborative reflection for team workflows
• Predictive reflection for proactive issue identification
• Automated reflection scheduling based on work patterns

Boundaries

This session command will:

• Provide robust session lifecycle management with strict performance requirements
• Integrate seamlessly with Serena MCP for comprehensive session capabilities
• Maintain context continuity and cross-session persistence effectively
• Support complex multi-session workflows with intelligent state management
• Deliver session operations within strict performance targets consistently
• Bridge TodoWrite patterns with advanced Serena reflection capabilities

This session command will not:

• Operate without proper Serena MCP integration and connectivity
• Compromise performance targets for additional functionality
• Proceed without proper session state validation and integrity checks
• Function without adequate error handling and recovery mechanisms
• Skip TodoWrite integration and compatibility maintenance
• Ignore reflection quality metrics and validation requirements