aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/dev-suggest-refactoring.md

@@ -1,871 +1,871 @@
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: devSuggestRefactoring()
-responsável: Dex (Builder)
-responsavel_type: Agente
-atomic_layer: Strategy
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-20 min (estimated)
-cost_estimated: $0.003-0.015
-token_usage: ~2,000-8,000 tokens
-```
-
-**Optimization Notes:**
-- Iterative analysis with depth limits; cache intermediate results; batch similar operations
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - development
-  - code
-updated_at: 2025-11-17
-```
-
----
-
-checklists:
-  - dev-master-checklist.md
----
-
-# Suggest Refactoring - AIOS Developer Task
-
-## Purpose
-Analyze code and suggest automated refactoring opportunities to improve code quality, maintainability, and performance.
-
-## Command Pattern
-```
-*suggest-refactoring <path> [options]
-```
-
-## Parameters
-- `path`: File or directory path to analyze
-- `options`: Refactoring analysis configuration
-
-### Options
-- `--patterns <types>`: Comma-separated refactoring patterns to check
-- `--threshold <level>`: Minimum impact threshold (1-10, default: 3)
-- `--limit <count>`: Maximum suggestions per file (default: 10)
-- `--apply <id>`: Apply specific suggestion by ID
-- `--apply-all`: Apply all suggestions with confirmation
-- `--export <file>`: Export suggestions to file
-- `--recursive`: Analyze directories recursively
-- `--exclude <patterns>`: Exclude file patterns (e.g., "*.test.js")
-- `--dry-run`: Show what would be changed without applying
-
-## Refactoring Patterns
-- `extract_method`: Extract long methods into smaller ones
-- `extract_variable`: Extract complex expressions
-- `introduce_parameter_object`: Group related parameters
-- `replace_conditional`: Replace conditionals with polymorphism
-- `inline_temp`: Inline single-use variables
-- `remove_dead_code`: Remove unreachable code
-- `consolidate_duplicates`: Extract duplicate code
-- `simplify_conditionals`: Flatten nested conditionals
-- `replace_magic_numbers`: Extract constants
-- `decompose_class`: Split large classes
-
-## Examples
-```bash
-# Analyze single file
-*suggest-refactoring aios-core/scripts/complex-utility.js
-
-# Analyze directory with specific patterns
-*suggest-refactoring aios-core/agents --patterns extract_method,decompose_class --recursive
-
-# Apply high-impact suggestions
-*suggest-refactoring aios-core/utils --threshold 7 --apply-all
-
-# Export suggestions for review
-*suggest-refactoring . --recursive --export refactoring-report.json
-
-# Dry run to see changes
-*suggest-refactoring aios-core/agents/developer.md --apply ref-001 --dry-run
-```
-
-## Implementation
-
-```javascript
-const fs = require('fs').promises;
-const path = require('path');
-const chalk = require('chalk');
-const inquirer = require('inquirer');
-const glob = require('glob').promises;
-
-class SuggestRefactoringTask {
-  constructor() {
-    this.taskName = 'suggest-refactoring';
-    this.description = 'Suggest automated refactoring opportunities';
-    this.rootPath = process.cwd();
-    this.refactoringSuggester = null;
-    this.suggestions = [];
-    this.appliedRefactorings = [];
-  }
-
-  async execute(params) {
-    try {
-      console.log(chalk.blue('🔧 AIOS Refactoring Analysis'));
-      console.log(chalk.gray('Analyzing code for refactoring opportunities\n'));
-
-      // Parse parameters
-      const config = await this.parseParameters(params);
-      
-      // Initialize dependencies
-      await this.initializeDependencies();
-
-      // Get files to analyze
-      const files = await this.getFilesToAnalyze(config);
-      
-      if (files.length === 0) {
-        console.log(chalk.yellow('No files found to analyze'));
-        return { success: true, suggestions: [] };
-      }
-
-      console.log(chalk.gray(`Found ${files.length} files to analyze\n`));
-
-      // Execute based on mode
-      if (config.apply) {
-        // Apply specific suggestion
-        await this.applySuggestion(config.apply, config);
-      } else if (config.applyAll) {
-        // Analyze and apply all suggestions
-        await this.analyzeFiles(files, config);
-        await this.applyAllSuggestions(config);
-      } else {
-        // Just analyze and show suggestions
-        await this.analyzeFiles(files, config);
-        await this.displaySuggestions(config);
-      }
-
-      // Export if requested
-      if (config.export) {
-        await this.exportSuggestions(config.export);
-      }
-
-      return {
-        success: true,
-        filesAnalyzed: files.length,
-        totalSuggestions: this.suggestions.length,
-        appliedRefactorings: this.appliedRefactorings.length
-      };
-
-    } catch (error) {
-      console.error(chalk.red(`\n❌ Refactoring analysis failed: ${error.message}`));
-      throw error;
-    }
-  }
-
-  async parseParameters(params) {
-    if (params.length < 1) {
-      throw new Error('Usage: *suggest-refactoring <path> [options]');
-    }
-
-    const config = {
-      targetPath: params[0],
-      patterns: null,
-      threshold: 3,
-      limit: 10,
-      apply: null,
-      applyAll: false,
-      export: null,
-      recursive: false,
-      exclude: [],
-      dryRun: false
-    };
-
-    // Parse options
-    for (let i = 1; i < params.length; i++) {
-      const param = params[i];
-      
-      if (param === '--recursive') {
-        config.recursive = true;
-      } else if (param === '--apply-all') {
-        config.applyAll = true;
-      } else if (param === '--dry-run') {
-        config.dryRun = true;
-      } else if (param.startsWith('--patterns') && params[i + 1]) {
-        config.patterns = params[++i].split(',').map(p => p.trim());
-      } else if (param.startsWith('--threshold') && params[i + 1]) {
-        config.threshold = parseInt(params[++i]);
-      } else if (param.startsWith('--limit') && params[i + 1]) {
-        config.limit = parseInt(params[++i]);
-      } else if (param.startsWith('--apply') && params[i + 1]) {
-        config.apply = params[++i];
-      } else if (param.startsWith('--export') && params[i + 1]) {
-        config.export = params[++i];
-      } else if (param.startsWith('--exclude') && params[i + 1]) {
-        config.exclude = params[++i].split(',').map(e => e.trim());
-      }
-    }
-
-    // Validate threshold
-    if (config.threshold < 1 || config.threshold > 10) {
-      throw new Error('Threshold must be between 1 and 10');
-    }
-
-    return config;
-  }
-
-  async initializeDependencies() {
-    try {
-      const RefactoringSuggester = require('../scripts/refactoring-suggester');
-      this.refactoringSuggester = new RefactoringSuggester({ rootPath: this.rootPath });
-
-    } catch (error) {
-      throw new Error(`Failed to initialize dependencies: ${error.message}`);
-    }
-  }
-
-  async getFilesToAnalyze(config) {
-    const targetPath = path.resolve(this.rootPath, config.targetPath);
-    const files = [];
-
-    try {
-      const stats = await fs.stat(targetPath);
-      
-      if (stats.isFile()) {
-        // Single file
-        if (this.shouldAnalyzeFile(targetPath, config)) {
-          files.push(targetPath);
-        }
-      } else if (stats.isDirectory()) {
-        // Directory
-        const pattern = config.recursive ? '**/*.{js,jsx,ts,tsx}' : '*.{js,jsx,ts,tsx}';
-        const globPattern = path.join(targetPath, pattern);
-        
-        const matches = await glob(globPattern, {
-          ignore: config.exclude.map(e => path.join(targetPath, '**', e)),
-          nodir: true
-        });
-        
-        for (const match of matches) {
-          if (this.shouldAnalyzeFile(match, config)) {
-            files.push(match);
-          }
-        }
-      }
-    } catch (error) {
-      console.warn(chalk.yellow(`Cannot access ${targetPath}: ${error.message}`));
-    }
-
-    return files;
-  }
-
-  shouldAnalyzeFile(filePath, config) {
-    // Skip test files unless explicitly included
-    if (filePath.includes('.test.') || filePath.includes('.spec.')) {
-      return false;
-    }
-    
-    // Skip minified files
-    if (filePath.includes('.min.')) {
-      return false;
-    }
-    
-    // Skip node_modules
-    if (filePath.includes('node_modules')) {
-      return false;
-    }
-    
-    // Check file extension
-    const ext = path.extname(filePath);
-    return ['.js', '.jsx', '.ts', '.tsx'].includes(ext);
-  }
-
-  async analyzeFiles(files, config) {
-    console.log(chalk.blue('🔍 Analyzing files...'));
-    
-    const progressInterval = Math.max(1, Math.floor(files.length / 20));
-    
-    for (let i = 0; i < files.length; i++) {
-      const file = files[i];
-      
-      try {
-        const result = await this.refactoringSuggester.analyzeCode(file, {
-          patterns: config.patterns
-        });
-        
-        if (result.suggestions && result.suggestions.length > 0) {
-          // Filter by threshold and limit
-          const filteredSuggestions = result.suggestions
-            .filter(s => s.impact >= config.threshold)
-            .slice(0, config.limit);
-          
-          // Add to global suggestions with unique IDs
-          for (const suggestion of filteredSuggestions) {
-            suggestion.id = `ref-${this.suggestions.length + 1}`;
-            suggestion.file = path.relative(this.rootPath, file);
-            this.suggestions.push(suggestion);
-          }
-        }
-        
-        // Show progress
-        if (i % progressInterval === 0) {
-          const progress = Math.floor((i / files.length) * 100);
-          process.stdout.write(`\rProgress: ${progress}%`);
-        }
-        
-      } catch (error) {
-        console.warn(chalk.yellow(`\nFailed to analyze ${file}: ${error.message}`));
-      }
-    }
-    
-    console.log('\rProgress: 100%\n');
-  }
-
-  async displaySuggestions(config) {
-    if (this.suggestions.length === 0) {
-      console.log(chalk.yellow('No refactoring suggestions found above threshold'));
-      return;
-    }
-
-    console.log(chalk.blue(`\n📋 Found ${this.suggestions.length} refactoring suggestions:\n`));
-
-    // Group by file
-    const byFile = {};
-    for (const suggestion of this.suggestions) {
-      if (!byFile[suggestion.file]) {
-        byFile[suggestion.file] = [];
-      }
-      byFile[suggestion.file].push(suggestion);
-    }
-
-    // Display suggestions
-    for (const [file, suggestions] of Object.entries(byFile)) {
-      console.log(chalk.blue(`\n📄 ${file}`));
-      console.log(chalk.gray('─'.repeat(50)));
-      
-      for (const suggestion of suggestions) {
-        this.displaySuggestion(suggestion);
-      }
-    }
-
-    // Show statistics
-    this.displayStatistics();
-
-    // Show next steps
-    console.log(chalk.blue('\n📌 Next Steps:'));
-    console.log('1. Review suggestions carefully');
-    console.log(`2. Apply specific suggestion: *suggest-refactoring ${config.targetPath} --apply <id>`);
-    console.log(`3. Apply all suggestions: *suggest-refactoring ${config.targetPath} --apply-all`);
-    console.log(`4. Export for team review: *suggest-refactoring ${config.targetPath} --export report.json`);
-  }
-
-  displaySuggestion(suggestion) {
-    const priorityColors = {
-      high: chalk.red,
-      medium: chalk.yellow,
-      low: chalk.gray
-    };
-    
-    const priorityColor = priorityColors[suggestion.priority] || chalk.gray;
-    
-    console.log(`\n${chalk.gray(suggestion.id)} ${priorityColor(`[${suggestion.priority.toUpperCase()}]`)} ${suggestion.description}`);
-    console.log(`   ${chalk.gray('Location:')} Lines ${suggestion.location.start}-${suggestion.location.end}`);
-    console.log(`   ${chalk.gray('Impact:')} ${this.formatImpact(suggestion.impact)}`);
-    console.log(`   ${chalk.gray('Type:')} ${suggestion.pattern}`);
-    console.log(`   ${chalk.gray('Details:')} ${suggestion.details}`);
-    
-    if (suggestion.suggestedRefactoring && suggestion.suggestedRefactoring.action) {
-      console.log(`   ${chalk.gray('Action:')} ${suggestion.suggestedRefactoring.action}`);
-    }
-  }
-
-  formatImpact(impact) {
-    const bar = '█'.repeat(impact) + '░'.repeat(10 - impact);
-    
-    if (impact >= 8) {
-      return chalk.red(bar) + ` (${impact}/10)`;
-    } else if (impact >= 5) {
-      return chalk.yellow(bar) + ` (${impact}/10)`;
-    } else {
-      return chalk.gray(bar) + ` (${impact}/10)`;
-    }
-  }
-
-  async applySuggestion(suggestionId, config) {
-    const suggestion = this.suggestions.find(s => s.id === suggestionId);
-    
-    if (!suggestion) {
-      // Try to load from previous analysis
-      const loaded = await this.loadSuggestion(suggestionId);
-      if (!loaded) {
-        throw new Error(`Suggestion not found: ${suggestionId}`);
-      }
-      suggestion = loaded;
-    }
-
-    console.log(chalk.blue('\n🔧 Applying Refactoring'));
-    console.log(chalk.gray('─'.repeat(50)));
-    this.displaySuggestion(suggestion);
-
-    if (config.dryRun) {
-      console.log(chalk.yellow('\n⚠️ DRY RUN - No changes will be made'));
-      await this.showRefactoringPreview(suggestion);
-      return;
-    }
-
-    // Confirm application
-    const { confirm } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'confirm',
-      message: 'Apply this refactoring?',
-      default: true
-    }]);
-
-    if (!confirm) {
-      console.log(chalk.gray('Refactoring cancelled'));
-      return;
-    }
-
-    // Apply the refactoring
-    try {
-      const result = await this.refactoringSuggester.applySuggestion(suggestion);
-      
-      if (result.success) {
-        console.log(chalk.green('✅ Refactoring applied successfully'));
-        this.appliedRefactorings.push({
-          suggestion,
-          result,
-          timestamp: new Date().toISOString()
-        });
-        
-        // Show changes
-        for (const change of result.changes) {
-          console.log(chalk.gray(`   - ${change.description}`));
-        }
-      } else {
-        console.error(chalk.red(`Failed to apply refactoring: ${result.error}`));
-      }
-    } catch (error) {
-      console.error(chalk.red(`Error applying refactoring: ${error.message}`));
-    }
-  }
-
-  async applyAllSuggestions(config) {
-    if (this.suggestions.length === 0) {
-      console.log(chalk.yellow('No suggestions to apply'));
-      return;
-    }
-
-    console.log(chalk.blue(`\n🔧 Applying ${this.suggestions.length} refactorings`));
-    
-    // Group by type for better user experience
-    const byType = {};
-    for (const suggestion of this.suggestions) {
-      if (!byType[suggestion.type]) {
-        byType[suggestion.type] = [];
-      }
-      byType[suggestion.type].push(suggestion);
-    }
-
-    // Show summary
-    console.log(chalk.gray('\nRefactorings by type:'));
-    for (const [type, suggestions] of Object.entries(byType)) {
-      console.log(`  ${type}: ${suggestions.length}`);
-    }
-
-    if (config.dryRun) {
-      console.log(chalk.yellow('\n⚠️ DRY RUN - No changes will be made'));
-      return;
-    }
-
-    // Confirm batch application
-    const { confirmAll } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'confirmAll',
-      message: `Apply all ${this.suggestions.length} refactorings?`,
-      default: false
-    }]);
-
-    if (!confirmAll) {
-      // Ask for individual confirmation
-      await this.applySelectiveSuggestions(config);
-      return;
-    }
-
-    // Apply all suggestions
-    let applied = 0;
-    let failed = 0;
-
-    for (const suggestion of this.suggestions) {
-      try {
-        console.log(chalk.gray(`\nApplying ${suggestion.id}: ${suggestion.description}`));
-        
-        const result = await this.refactoringSuggester.applySuggestion(suggestion);
-        
-        if (result.success) {
-          applied++;
-          this.appliedRefactorings.push({
-            suggestion,
-            result,
-            timestamp: new Date().toISOString()
-          });
-        } else {
-          failed++;
-          console.error(chalk.red(`  Failed: ${result.error}`));
-        }
-      } catch (error) {
-        failed++;
-        console.error(chalk.red(`  Error: ${error.message}`));
-      }
-    }
-
-    console.log(chalk.blue('\n📊 Application Summary:'));
-    console.log(chalk.green(`  ✅ Applied: ${applied}`));
-    if (failed > 0) {
-      console.log(chalk.red(`  ❌ Failed: ${failed}`));
-    }
-  }
-
-  async applySelectiveSuggestions(config) {
-    const choices = this.suggestions.map(s => ({
-      name: `${s.id} - ${s.description} (${s.file})`,
-      value: s.id,
-      checked: s.impact >= 7 // Pre-check high impact
-    }));
-
-    const { selected } = await inquirer.prompt([{
-      type: 'checkbox',
-      name: 'selected',
-      message: 'Select refactorings to apply:',
-      choices,
-      pageSize: 15
-    }]);
-
-    if (selected.length === 0) {
-      console.log(chalk.gray('No refactorings selected'));
-      return;
-    }
-
-    // Apply selected suggestions
-    for (const id of selected) {
-      const suggestion = this.suggestions.find(s => s.id === id);
-      await this.applySuggestion(id, config);
-    }
-  }
-
-  async showRefactoringPreview(suggestion) {
-    console.log(chalk.blue('\n📝 Refactoring Preview:'));
-    
-    // This would show actual code changes
-    // For now, show the refactoring plan
-    if (suggestion.suggestedRefactoring) {
-      console.log(chalk.gray(JSON.stringify(suggestion.suggestedRefactoring, null, 2)));
-    }
-  }
-
-  async loadSuggestion(suggestionId) {
-    // Try to load from cache or previous export
-    const cacheFile = path.join(this.rootPath, '.aios', 'refactoring', `${suggestionId}.json`);
-    
-    try {
-      const content = await fs.readFile(cacheFile, 'utf-8');
-      return JSON.parse(content);
-    } catch (error) {
-      return null;
-    }
-  }
-
-  async exportSuggestions(exportPath) {
-    console.log(chalk.blue('\n📤 Exporting suggestions...'));
-    
-    const exportData = {
-      version: 1,
-      exportDate: new Date().toISOString(),
-      analysisPath: this.rootPath,
-      totalSuggestions: this.suggestions.length,
-      statistics: this.refactoringSuggester.getStatistics(),
-      suggestions: this.suggestions.map(s => ({
-        ...s,
-        file: s.file || s.filePath
-      }))
-    };
-
-    await fs.writeFile(exportPath, JSON.stringify(exportData, null, 2));
-    console.log(chalk.green(`✅ Exported ${this.suggestions.length} suggestions to: ${exportPath}`));
-  }
-
-  displayStatistics() {
-    const stats = this.refactoringSuggester.getStatistics();
-    
-    console.log(chalk.blue('\n📊 Refactoring Statistics:'));
-    console.log(chalk.gray('─'.repeat(50)));
-    
-    console.log(`Total suggestions: ${stats.totalSuggestions}`);
-    console.log(`Average impact: ${stats.averageImpact}/10`);
-    
-    console.log('\nBy priority:');
-    for (const [priority, count] of Object.entries(stats.byPriority)) {
-      console.log(`  ${priority}: ${count}`);
-    }
-    
-    console.log('\nBy type:');
-    const sortedTypes = Object.entries(stats.byType)
-      .sort(([,a], [,b]) => b - a)
-      .slice(0, 5);
-    
-    for (const [type, count] of sortedTypes) {
-      console.log(`  ${type}: ${count}`);
-    }
-  }
-}
-
-module.exports = SuggestRefactoringTask;
-```
-
-## Integration Points
-
-### Refactoring Suggester
-- Core analysis engine
-- Pattern detection
-- Suggestion generation
-- Refactoring application
-
-### AST Processing
-- Code parsing
-- Pattern matching
-- Code transformation
-- Generation
-
-### Pattern Library
-- Refactoring patterns
-- Detection algorithms
-- Application strategies
-- Success metrics
-
-### Code Metrics
-- Complexity analysis
-- Code quality metrics
-- Impact calculation
-- Priority assignment
-
-## Refactoring Workflow
-
-### Analysis Phase
-1. Parse code into AST
-2. Calculate code metrics
-3. Run pattern detectors
-4. Generate suggestions
-5. Prioritize by impact
-
-### Review Phase
-1. Display suggestions
-2. Group by file/type
-3. Show impact analysis
-4. Provide preview
-5. Export for review
-
-### Application Phase
-1. Confirm changes
-2. Create backup
-3. Apply transformation
-4. Validate result
-5. Update metrics
-
-## Best Practices
-
-### Safe Refactoring
-- Always backup before changes
-- Validate syntax after refactoring
-- Run tests after changes
-- Use dry-run for preview
-- Apply incrementally
-
-### Pattern Selection
-- Start with high-impact patterns
-- Focus on code hotspots
-- Consider team preferences
-- Respect coding standards
-- Monitor effectiveness
-
-### Continuous Improvement
-- Track refactoring success
-- Learn from applied patterns
-- Update pattern library
-- Share successful refactorings
-- Measure code quality trends
-
-## Security Considerations
-- Validate refactoring safety
-- Preserve functionality
-- Maintain security patterns
-- Audit changes
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: devSuggestRefactoring()
+responsável: Dex (Builder)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - development
+  - code
+updated_at: 2025-11-17
+```
+
+---
+
+checklists:
+  - dev-master-checklist.md
+---
+
+# Suggest Refactoring - AIOS Developer Task
+
+## Purpose
+Analyze code and suggest automated refactoring opportunities to improve code quality, maintainability, and performance.
+
+## Command Pattern
+```
+*suggest-refactoring <path> [options]
+```
+
+## Parameters
+- `path`: File or directory path to analyze
+- `options`: Refactoring analysis configuration
+
+### Options
+- `--patterns <types>`: Comma-separated refactoring patterns to check
+- `--threshold <level>`: Minimum impact threshold (1-10, default: 3)
+- `--limit <count>`: Maximum suggestions per file (default: 10)
+- `--apply <id>`: Apply specific suggestion by ID
+- `--apply-all`: Apply all suggestions with confirmation
+- `--export <file>`: Export suggestions to file
+- `--recursive`: Analyze directories recursively
+- `--exclude <patterns>`: Exclude file patterns (e.g., "*.test.js")
+- `--dry-run`: Show what would be changed without applying
+
+## Refactoring Patterns
+- `extract_method`: Extract long methods into smaller ones
+- `extract_variable`: Extract complex expressions
+- `introduce_parameter_object`: Group related parameters
+- `replace_conditional`: Replace conditionals with polymorphism
+- `inline_temp`: Inline single-use variables
+- `remove_dead_code`: Remove unreachable code
+- `consolidate_duplicates`: Extract duplicate code
+- `simplify_conditionals`: Flatten nested conditionals
+- `replace_magic_numbers`: Extract constants
+- `decompose_class`: Split large classes
+
+## Examples
+```bash
+# Analyze single file
+*suggest-refactoring aios-core/scripts/complex-utility.js
+
+# Analyze directory with specific patterns
+*suggest-refactoring aios-core/agents --patterns extract_method,decompose_class --recursive
+
+# Apply high-impact suggestions
+*suggest-refactoring aios-core/utils --threshold 7 --apply-all
+
+# Export suggestions for review
+*suggest-refactoring . --recursive --export refactoring-report.json
+
+# Dry run to see changes
+*suggest-refactoring aios-core/agents/developer.md --apply ref-001 --dry-run
+```
+
+## Implementation
+
+```javascript
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const glob = require('glob').promises;
+
+class SuggestRefactoringTask {
+  constructor() {
+    this.taskName = 'suggest-refactoring';
+    this.description = 'Suggest automated refactoring opportunities';
+    this.rootPath = process.cwd();
+    this.refactoringSuggester = null;
+    this.suggestions = [];
+    this.appliedRefactorings = [];
+  }
+
+  async execute(params) {
+    try {
+      console.log(chalk.blue('🔧 AIOS Refactoring Analysis'));
+      console.log(chalk.gray('Analyzing code for refactoring opportunities\n'));
+
+      // Parse parameters
+      const config = await this.parseParameters(params);
+      
+      // Initialize dependencies
+      await this.initializeDependencies();
+
+      // Get files to analyze
+      const files = await this.getFilesToAnalyze(config);
+      
+      if (files.length === 0) {
+        console.log(chalk.yellow('No files found to analyze'));
+        return { success: true, suggestions: [] };
+      }
+
+      console.log(chalk.gray(`Found ${files.length} files to analyze\n`));
+
+      // Execute based on mode
+      if (config.apply) {
+        // Apply specific suggestion
+        await this.applySuggestion(config.apply, config);
+      } else if (config.applyAll) {
+        // Analyze and apply all suggestions
+        await this.analyzeFiles(files, config);
+        await this.applyAllSuggestions(config);
+      } else {
+        // Just analyze and show suggestions
+        await this.analyzeFiles(files, config);
+        await this.displaySuggestions(config);
+      }
+
+      // Export if requested
+      if (config.export) {
+        await this.exportSuggestions(config.export);
+      }
+
+      return {
+        success: true,
+        filesAnalyzed: files.length,
+        totalSuggestions: this.suggestions.length,
+        appliedRefactorings: this.appliedRefactorings.length
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Refactoring analysis failed: ${error.message}`));
+      throw error;
+    }
+  }
+
+  async parseParameters(params) {
+    if (params.length < 1) {
+      throw new Error('Usage: *suggest-refactoring <path> [options]');
+    }
+
+    const config = {
+      targetPath: params[0],
+      patterns: null,
+      threshold: 3,
+      limit: 10,
+      apply: null,
+      applyAll: false,
+      export: null,
+      recursive: false,
+      exclude: [],
+      dryRun: false
+    };
+
+    // Parse options
+    for (let i = 1; i < params.length; i++) {
+      const param = params[i];
+      
+      if (param === '--recursive') {
+        config.recursive = true;
+      } else if (param === '--apply-all') {
+        config.applyAll = true;
+      } else if (param === '--dry-run') {
+        config.dryRun = true;
+      } else if (param.startsWith('--patterns') && params[i + 1]) {
+        config.patterns = params[++i].split(',').map(p => p.trim());
+      } else if (param.startsWith('--threshold') && params[i + 1]) {
+        config.threshold = parseInt(params[++i]);
+      } else if (param.startsWith('--limit') && params[i + 1]) {
+        config.limit = parseInt(params[++i]);
+      } else if (param.startsWith('--apply') && params[i + 1]) {
+        config.apply = params[++i];
+      } else if (param.startsWith('--export') && params[i + 1]) {
+        config.export = params[++i];
+      } else if (param.startsWith('--exclude') && params[i + 1]) {
+        config.exclude = params[++i].split(',').map(e => e.trim());
+      }
+    }
+
+    // Validate threshold
+    if (config.threshold < 1 || config.threshold > 10) {
+      throw new Error('Threshold must be between 1 and 10');
+    }
+
+    return config;
+  }
+
+  async initializeDependencies() {
+    try {
+      const RefactoringSuggester = require('../scripts/refactoring-suggester');
+      this.refactoringSuggester = new RefactoringSuggester({ rootPath: this.rootPath });
+
+    } catch (error) {
+      throw new Error(`Failed to initialize dependencies: ${error.message}`);
+    }
+  }
+
+  async getFilesToAnalyze(config) {
+    const targetPath = path.resolve(this.rootPath, config.targetPath);
+    const files = [];
+
+    try {
+      const stats = await fs.stat(targetPath);
+      
+      if (stats.isFile()) {
+        // Single file
+        if (this.shouldAnalyzeFile(targetPath, config)) {
+          files.push(targetPath);
+        }
+      } else if (stats.isDirectory()) {
+        // Directory
+        const pattern = config.recursive ? '**/*.{js,jsx,ts,tsx}' : '*.{js,jsx,ts,tsx}';
+        const globPattern = path.join(targetPath, pattern);
+        
+        const matches = await glob(globPattern, {
+          ignore: config.exclude.map(e => path.join(targetPath, '**', e)),
+          nodir: true
+        });
+        
+        for (const match of matches) {
+          if (this.shouldAnalyzeFile(match, config)) {
+            files.push(match);
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(chalk.yellow(`Cannot access ${targetPath}: ${error.message}`));
+    }
+
+    return files;
+  }
+
+  shouldAnalyzeFile(filePath, config) {
+    // Skip test files unless explicitly included
+    if (filePath.includes('.test.') || filePath.includes('.spec.')) {
+      return false;
+    }
+    
+    // Skip minified files
+    if (filePath.includes('.min.')) {
+      return false;
+    }
+    
+    // Skip node_modules
+    if (filePath.includes('node_modules')) {
+      return false;
+    }
+    
+    // Check file extension
+    const ext = path.extname(filePath);
+    return ['.js', '.jsx', '.ts', '.tsx'].includes(ext);
+  }
+
+  async analyzeFiles(files, config) {
+    console.log(chalk.blue('🔍 Analyzing files...'));
+    
+    const progressInterval = Math.max(1, Math.floor(files.length / 20));
+    
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i];
+      
+      try {
+        const result = await this.refactoringSuggester.analyzeCode(file, {
+          patterns: config.patterns
+        });
+        
+        if (result.suggestions && result.suggestions.length > 0) {
+          // Filter by threshold and limit
+          const filteredSuggestions = result.suggestions
+            .filter(s => s.impact >= config.threshold)
+            .slice(0, config.limit);
+          
+          // Add to global suggestions with unique IDs
+          for (const suggestion of filteredSuggestions) {
+            suggestion.id = `ref-${this.suggestions.length + 1}`;
+            suggestion.file = path.relative(this.rootPath, file);
+            this.suggestions.push(suggestion);
+          }
+        }
+        
+        // Show progress
+        if (i % progressInterval === 0) {
+          const progress = Math.floor((i / files.length) * 100);
+          process.stdout.write(`\rProgress: ${progress}%`);
+        }
+        
+      } catch (error) {
+        console.warn(chalk.yellow(`\nFailed to analyze ${file}: ${error.message}`));
+      }
+    }
+    
+    console.log('\rProgress: 100%\n');
+  }
+
+  async displaySuggestions(config) {
+    if (this.suggestions.length === 0) {
+      console.log(chalk.yellow('No refactoring suggestions found above threshold'));
+      return;
+    }
+
+    console.log(chalk.blue(`\n📋 Found ${this.suggestions.length} refactoring suggestions:\n`));
+
+    // Group by file
+    const byFile = {};
+    for (const suggestion of this.suggestions) {
+      if (!byFile[suggestion.file]) {
+        byFile[suggestion.file] = [];
+      }
+      byFile[suggestion.file].push(suggestion);
+    }
+
+    // Display suggestions
+    for (const [file, suggestions] of Object.entries(byFile)) {
+      console.log(chalk.blue(`\n📄 ${file}`));
+      console.log(chalk.gray('─'.repeat(50)));
+      
+      for (const suggestion of suggestions) {
+        this.displaySuggestion(suggestion);
+      }
+    }
+
+    // Show statistics
+    this.displayStatistics();
+
+    // Show next steps
+    console.log(chalk.blue('\n📌 Next Steps:'));
+    console.log('1. Review suggestions carefully');
+    console.log(`2. Apply specific suggestion: *suggest-refactoring ${config.targetPath} --apply <id>`);
+    console.log(`3. Apply all suggestions: *suggest-refactoring ${config.targetPath} --apply-all`);
+    console.log(`4. Export for team review: *suggest-refactoring ${config.targetPath} --export report.json`);
+  }
+
+  displaySuggestion(suggestion) {
+    const priorityColors = {
+      high: chalk.red,
+      medium: chalk.yellow,
+      low: chalk.gray
+    };
+    
+    const priorityColor = priorityColors[suggestion.priority] || chalk.gray;
+    
+    console.log(`\n${chalk.gray(suggestion.id)} ${priorityColor(`[${suggestion.priority.toUpperCase()}]`)} ${suggestion.description}`);
+    console.log(`   ${chalk.gray('Location:')} Lines ${suggestion.location.start}-${suggestion.location.end}`);
+    console.log(`   ${chalk.gray('Impact:')} ${this.formatImpact(suggestion.impact)}`);
+    console.log(`   ${chalk.gray('Type:')} ${suggestion.pattern}`);
+    console.log(`   ${chalk.gray('Details:')} ${suggestion.details}`);
+    
+    if (suggestion.suggestedRefactoring && suggestion.suggestedRefactoring.action) {
+      console.log(`   ${chalk.gray('Action:')} ${suggestion.suggestedRefactoring.action}`);
+    }
+  }
+
+  formatImpact(impact) {
+    const bar = '█'.repeat(impact) + '░'.repeat(10 - impact);
+    
+    if (impact >= 8) {
+      return chalk.red(bar) + ` (${impact}/10)`;
+    } else if (impact >= 5) {
+      return chalk.yellow(bar) + ` (${impact}/10)`;
+    } else {
+      return chalk.gray(bar) + ` (${impact}/10)`;
+    }
+  }
+
+  async applySuggestion(suggestionId, config) {
+    const suggestion = this.suggestions.find(s => s.id === suggestionId);
+    
+    if (!suggestion) {
+      // Try to load from previous analysis
+      const loaded = await this.loadSuggestion(suggestionId);
+      if (!loaded) {
+        throw new Error(`Suggestion not found: ${suggestionId}`);
+      }
+      suggestion = loaded;
+    }
+
+    console.log(chalk.blue('\n🔧 Applying Refactoring'));
+    console.log(chalk.gray('─'.repeat(50)));
+    this.displaySuggestion(suggestion);
+
+    if (config.dryRun) {
+      console.log(chalk.yellow('\n⚠️ DRY RUN - No changes will be made'));
+      await this.showRefactoringPreview(suggestion);
+      return;
+    }
+
+    // Confirm application
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Apply this refactoring?',
+      default: true
+    }]);
+
+    if (!confirm) {
+      console.log(chalk.gray('Refactoring cancelled'));
+      return;
+    }
+
+    // Apply the refactoring
+    try {
+      const result = await this.refactoringSuggester.applySuggestion(suggestion);
+      
+      if (result.success) {
+        console.log(chalk.green('✅ Refactoring applied successfully'));
+        this.appliedRefactorings.push({
+          suggestion,
+          result,
+          timestamp: new Date().toISOString()
+        });
+        
+        // Show changes
+        for (const change of result.changes) {
+          console.log(chalk.gray(`   - ${change.description}`));
+        }
+      } else {
+        console.error(chalk.red(`Failed to apply refactoring: ${result.error}`));
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error applying refactoring: ${error.message}`));
+    }
+  }
+
+  async applyAllSuggestions(config) {
+    if (this.suggestions.length === 0) {
+      console.log(chalk.yellow('No suggestions to apply'));
+      return;
+    }
+
+    console.log(chalk.blue(`\n🔧 Applying ${this.suggestions.length} refactorings`));
+    
+    // Group by type for better user experience
+    const byType = {};
+    for (const suggestion of this.suggestions) {
+      if (!byType[suggestion.type]) {
+        byType[suggestion.type] = [];
+      }
+      byType[suggestion.type].push(suggestion);
+    }
+
+    // Show summary
+    console.log(chalk.gray('\nRefactorings by type:'));
+    for (const [type, suggestions] of Object.entries(byType)) {
+      console.log(`  ${type}: ${suggestions.length}`);
+    }
+
+    if (config.dryRun) {
+      console.log(chalk.yellow('\n⚠️ DRY RUN - No changes will be made'));
+      return;
+    }
+
+    // Confirm batch application
+    const { confirmAll } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirmAll',
+      message: `Apply all ${this.suggestions.length} refactorings?`,
+      default: false
+    }]);
+
+    if (!confirmAll) {
+      // Ask for individual confirmation
+      await this.applySelectiveSuggestions(config);
+      return;
+    }
+
+    // Apply all suggestions
+    let applied = 0;
+    let failed = 0;
+
+    for (const suggestion of this.suggestions) {
+      try {
+        console.log(chalk.gray(`\nApplying ${suggestion.id}: ${suggestion.description}`));
+        
+        const result = await this.refactoringSuggester.applySuggestion(suggestion);
+        
+        if (result.success) {
+          applied++;
+          this.appliedRefactorings.push({
+            suggestion,
+            result,
+            timestamp: new Date().toISOString()
+          });
+        } else {
+          failed++;
+          console.error(chalk.red(`  Failed: ${result.error}`));
+        }
+      } catch (error) {
+        failed++;
+        console.error(chalk.red(`  Error: ${error.message}`));
+      }
+    }
+
+    console.log(chalk.blue('\n📊 Application Summary:'));
+    console.log(chalk.green(`  ✅ Applied: ${applied}`));
+    if (failed > 0) {
+      console.log(chalk.red(`  ❌ Failed: ${failed}`));
+    }
+  }
+
+  async applySelectiveSuggestions(config) {
+    const choices = this.suggestions.map(s => ({
+      name: `${s.id} - ${s.description} (${s.file})`,
+      value: s.id,
+      checked: s.impact >= 7 // Pre-check high impact
+    }));
+
+    const { selected } = await inquirer.prompt([{
+      type: 'checkbox',
+      name: 'selected',
+      message: 'Select refactorings to apply:',
+      choices,
+      pageSize: 15
+    }]);
+
+    if (selected.length === 0) {
+      console.log(chalk.gray('No refactorings selected'));
+      return;
+    }
+
+    // Apply selected suggestions
+    for (const id of selected) {
+      const suggestion = this.suggestions.find(s => s.id === id);
+      await this.applySuggestion(id, config);
+    }
+  }
+
+  async showRefactoringPreview(suggestion) {
+    console.log(chalk.blue('\n📝 Refactoring Preview:'));
+    
+    // This would show actual code changes
+    // For now, show the refactoring plan
+    if (suggestion.suggestedRefactoring) {
+      console.log(chalk.gray(JSON.stringify(suggestion.suggestedRefactoring, null, 2)));
+    }
+  }
+
+  async loadSuggestion(suggestionId) {
+    // Try to load from cache or previous export
+    const cacheFile = path.join(this.rootPath, '.aios', 'refactoring', `${suggestionId}.json`);
+    
+    try {
+      const content = await fs.readFile(cacheFile, 'utf-8');
+      return JSON.parse(content);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  async exportSuggestions(exportPath) {
+    console.log(chalk.blue('\n📤 Exporting suggestions...'));
+    
+    const exportData = {
+      version: 1,
+      exportDate: new Date().toISOString(),
+      analysisPath: this.rootPath,
+      totalSuggestions: this.suggestions.length,
+      statistics: this.refactoringSuggester.getStatistics(),
+      suggestions: this.suggestions.map(s => ({
+        ...s,
+        file: s.file || s.filePath
+      }))
+    };
+
+    await fs.writeFile(exportPath, JSON.stringify(exportData, null, 2));
+    console.log(chalk.green(`✅ Exported ${this.suggestions.length} suggestions to: ${exportPath}`));
+  }
+
+  displayStatistics() {
+    const stats = this.refactoringSuggester.getStatistics();
+    
+    console.log(chalk.blue('\n📊 Refactoring Statistics:'));
+    console.log(chalk.gray('─'.repeat(50)));
+    
+    console.log(`Total suggestions: ${stats.totalSuggestions}`);
+    console.log(`Average impact: ${stats.averageImpact}/10`);
+    
+    console.log('\nBy priority:');
+    for (const [priority, count] of Object.entries(stats.byPriority)) {
+      console.log(`  ${priority}: ${count}`);
+    }
+    
+    console.log('\nBy type:');
+    const sortedTypes = Object.entries(stats.byType)
+      .sort(([,a], [,b]) => b - a)
+      .slice(0, 5);
+    
+    for (const [type, count] of sortedTypes) {
+      console.log(`  ${type}: ${count}`);
+    }
+  }
+}
+
+module.exports = SuggestRefactoringTask;
+```
+
+## Integration Points
+
+### Refactoring Suggester
+- Core analysis engine
+- Pattern detection
+- Suggestion generation
+- Refactoring application
+
+### AST Processing
+- Code parsing
+- Pattern matching
+- Code transformation
+- Generation
+
+### Pattern Library
+- Refactoring patterns
+- Detection algorithms
+- Application strategies
+- Success metrics
+
+### Code Metrics
+- Complexity analysis
+- Code quality metrics
+- Impact calculation
+- Priority assignment
+
+## Refactoring Workflow
+
+### Analysis Phase
+1. Parse code into AST
+2. Calculate code metrics
+3. Run pattern detectors
+4. Generate suggestions
+5. Prioritize by impact
+
+### Review Phase
+1. Display suggestions
+2. Group by file/type
+3. Show impact analysis
+4. Provide preview
+5. Export for review
+
+### Application Phase
+1. Confirm changes
+2. Create backup
+3. Apply transformation
+4. Validate result
+5. Update metrics
+
+## Best Practices
+
+### Safe Refactoring
+- Always backup before changes
+- Validate syntax after refactoring
+- Run tests after changes
+- Use dry-run for preview
+- Apply incrementally
+
+### Pattern Selection
+- Start with high-impact patterns
+- Focus on code hotspots
+- Consider team preferences
+- Respect coding standards
+- Monitor effectiveness
+
+### Continuous Improvement
+- Track refactoring success
+- Learn from applied patterns
+- Update pattern library
+- Share successful refactorings
+- Measure code quality trends
+
+## Security Considerations
+- Validate refactoring safety
+- Preserve functionality
+- Maintain security patterns
+- Audit changes
 - Test thoroughly