grimoire-framework 1.0.0

package/.grimoire/development/tasks/architect-analyze-impact.md

@@ -0,0 +1,828 @@
+# An
+## 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 (grimoire Task Format V1.0)
+
+```yaml
+task: architectAnalyzeImpact()
+responsável: Aria (Visionary)
+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:** .grimoire/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .grimoire/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .grimoire/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:
+  - analysis
+  - metrics
+updated_at: 2025-11-17
+```
+
+---
+
+alyze Impact - grimoire Developer Task
+
+## Purpose
+Analyze the potential impact of proposed component modifications on the broader Grimoire framework.
+
+## Command Pattern
+```
+*analyze-impact <modification-type> <component-path> [options]
+```
+
+## Parameters
+- `modification-type`: Type of modification (modify, deprecate, remove, refactor)
+- `component-path`: Path to the component being modified
+- `options`: Impact analysis configuration
+
+### Options
+- `--depth <level>`: Analysis depth (shallow, medium, deep)
+- `--include-tests`: Include test file impact analysis
+- `--risk-threshold <level>`: Risk threshold for warnings (low, medium, high, critical)
+- `--output-format <format>`: Output format (text, json, visual, html)
+- `--save-report <path>`: Save detailed report to file
+- `--approve-high-risk`: Skip approval workflow for high-risk changes
+- `--exclude-external`: Exclude external dependency analysis
+
+## Examples
+```bash
+# Analyze impact of modifying an agent
+*analyze-impact modify grimoire/agents/weather-agent.md --depth deep --include-tests
+
+# Analyze deprecation impact with visual output
+*analyze-impact deprecate grimoire/scripts/old-helper.js --output-format visual --save-report reports/deprecation-impact.html
+
+# Quick impact check for refactoring
+*analyze-impact refactor grimoire/tasks/process-data.md --depth shallow --risk-threshold medium
+
+# Analyze removal with approval workflow
+*analyze-impact remove grimoire/workflows/legacy-workflow.yaml --depth deep --save-report reports/removal-impact.json
+```
+
+## Implementation
+
+```javascript
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+class AnalyzeImpactTask {
+  constructor() {
+    this.taskName = 'analyze-impact';
+    this.description = 'Analyze potential impact of component modifications';
+    this.rootPath = process.cwd();
+    this.dependencyAnalyzer = null;
+    this.propagationPredictor = null;
+    this.riskAssessment = null;
+    this.visualGenerator = null;
+    this.approvalWorkflow = null;
+  }
+
+  async execute(params) {
+    try {
+      console.log(chalk.blue('🔍 grimoire Impact Analysis'));
+      console.log(chalk.gray('Analyzing potential impact of component modifications\\n'));
+
+      // Parse and validate parameters
+      const config = await this.parseParameters(params);
+      
+      // Initialize dependencies
+      await this.initializeDependencies();
+
+      // Validate target component exists
+      const targetComponent = await this.validateTargetComponent(config);
+
+      // Perform dependency impact analysis
+      console.log(chalk.gray('Analyzing dependency impact...'));
+      const dependencyImpact = await this.analyzeDependencyImpact(targetComponent, config);
+
+      // Predict change propagation
+      console.log(chalk.gray('Predicting change propagation...'));
+      const propagationAnalysis = await this.predictChangePropagation(targetComponent, dependencyImpact, config);
+
+      // Assess modification risks
+      console.log(chalk.gray('Assessing modification risks...'));
+      const riskAssessment = await this.assessModificationRisks(targetComponent, dependencyImpact, propagationAnalysis, config);
+
+      // Generate comprehensive impact report
+      const impactReport = await this.generateImpactReport(targetComponent, {
+        dependencyImpact,
+        propagationAnalysis,
+        riskAssessment
+      }, config);
+
+      // Display impact summary
+      await this.displayImpactSummary(impactReport);
+
+      // Generate visual representation if requested
+      if (config.outputFormat === 'visual' || config.outputFormat === 'html') {
+        console.log(chalk.gray('Generating visual impact representation...'));
+        await this.generateVisualRepresentation(impactReport, config);
+      }
+
+      // Save detailed report if requested
+      if (config.saveReport) {
+        await this.saveDetailedReport(impactReport, config.saveReport, config.outputFormat);
+      }
+
+      // Handle high-risk change approval workflow
+      if (riskAssessment.overallRisk === 'high' || riskAssessment.overallRisk === 'critical') {
+        if (!config.approveHighRisk) {
+          const approved = await this.handleHighRiskApproval(impactReport);
+          if (!approved) {
+            console.log(chalk.yellow('\\n⚠ High-risk modification requires approval before proceeding'));
+            return {
+              success: true,
+              requiresApproval: true,
+              riskLevel: riskAssessment.overallRisk,
+              impactSummary: impactReport.summary
+            };
+          }
+        }
+      }
+
+      // Display completion summary
+      console.log(chalk.green('\\n✅ Impact analysis completed'));
+      console.log(chalk.gray(`   Components analyzed: ${dependencyImpact.affectedComponents.length}`));
+      console.log(chalk.gray(`   Risk level: ${this.formatRiskLevel(riskAssessment.overallRisk)}`));
+      console.log(chalk.gray(`   Propagation depth: ${propagationAnalysis.maxDepth}`));
+
+      return {
+        success: true,
+        targetComponent: targetComponent.path,
+        riskLevel: riskAssessment.overallRisk,
+        affectedComponents: dependencyImpact.affectedComponents.length,
+        propagationDepth: propagationAnalysis.maxDepth,
+        requiresApproval: false,
+        impactReport: config.outputFormat === 'json' ? impactReport : impactReport.summary
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`\\n❌ Impact analysis failed: ${error.message}`));
+      throw error;
+    }
+  }
+
+  async parseParameters(params) {
+    if (params.length < 2) {
+      throw new Error('Usage: *analyze-impact <modification-type> <component-path> [options]');
+    }
+
+    const config = {
+      modificationType: params[0],
+      componentPath: params[1],
+      depth: 'medium',
+      includeTests: false,
+      riskThreshold: 'medium',
+      outputFormat: 'text',
+      saveReport: null,
+      approveHighRisk: false,
+      excludeExternal: false
+    };
+
+    // Parse options
+    for (let i = 2; i < params.length; i++) {
+      const param = params[i];
+      
+      if (param === '--include-tests') {
+        config.includeTests = true;
+      } else if (param === '--approve-high-risk') {
+        config.approveHighRisk = true;
+      } else if (param === '--exclude-external') {
+        config.excludeExternal = true;
+      } else if (param.startsWith('--depth') && params[i + 1]) {
+        config.depth = params[++i];
+      } else if (param.startsWith('--risk-threshold') && params[i + 1]) {
+        config.riskThreshold = params[++i];
+      } else if (param.startsWith('--output-format') && params[i + 1]) {
+        config.outputFormat = params[++i];
+      } else if (param.startsWith('--save-report') && params[i + 1]) {
+        config.saveReport = params[++i];
+      }
+    }
+
+    // Validation
+    const validModificationTypes = ['modify', 'deprecate', 'remove', 'refactor'];
+    if (!validModificationTypes.includes(config.modificationType)) {
+      throw new Error(`Invalid modification type: ${config.modificationType}. Must be one of: ${validModificationTypes.join(', ')}`);
+    }
+
+    const validDepths = ['shallow', 'medium', 'deep'];
+    if (!validDepths.includes(config.depth)) {
+      throw new Error(`Invalid depth: ${config.depth}. Must be one of: ${validDepths.join(', ')}`);
+    }
+
+    const validRiskThresholds = ['low', 'medium', 'high', 'critical'];
+    if (!validRiskThresholds.includes(config.riskThreshold)) {
+      throw new Error(`Invalid risk threshold: ${config.riskThreshold}. Must be one of: ${validRiskThresholds.join(', ')}`);
+    }
+
+    const validOutputFormats = ['text', 'json', 'visual', 'html'];
+    if (!validOutputFormats.includes(config.outputFormat)) {
+      throw new Error(`Invalid output format: ${config.outputFormat}. Must be one of: ${validOutputFormats.join(', ')}`);
+    }
+
+    return config;
+  }
+
+  async initializeDependencies() {
+    try {
+      // Initialize dependency impact analyzer
+      const DependencyImpactAnalyzer = require('../scripts/dependency-impact-analyzer');
+      this.dependencyAnalyzer = new DependencyImpactAnalyzer({ rootPath: this.rootPath });
+      await this.dependencyAnalyzer.initialize();
+
+      // Initialize change propagation predictor
+      // const ChangePropagationPredictor = require('../scripts/change-propagation-predictor'); // Archived in archived-utilities/ (Story 3.1.2)
+      // this.propagationPredictor = new ChangePropagationPredictor({ rootPath: this.rootPath }); // Archived in archived-utilities/ (Story 3.1.2)
+
+      // Initialize risk assessment
+      const ModificationRiskAssessment = require('../scripts/modification-risk-assessment');
+      this.riskAssessment = new ModificationRiskAssessment({ rootPath: this.rootPath });
+
+      // Initialize visual impact generator
+      const VisualImpactGenerator = require('../scripts/visual-impact-generator');
+      this.visualGenerator = new VisualImpactGenerator({ rootPath: this.rootPath });
+
+      // Initialize approval workflow
+      const ApprovalWorkflow = require('../scripts/approval-workflow');
+      this.approvalWorkflow = new ApprovalWorkflow({ rootPath: this.rootPath });
+
+    } catch (error) {
+      throw new Error(`Failed to initialize dependencies: ${error.message}`);
+    }
+  }
+
+  async validateTargetComponent(config) {
+    const fullPath = path.resolve(this.rootPath, config.componentPath);
+    
+    try {
+      const stats = await fs.stat(fullPath);
+      if (!stats.isFile()) {
+        throw new Error(`Target path is not a file: ${config.componentPath}`);
+      }
+
+      const content = await fs.readFile(fullPath, 'utf-8');
+      const componentType = this.determineComponentType(fullPath, content);
+
+      return {
+        path: config.componentPath,
+        fullPath: fullPath,
+        type: componentType,
+        content: content,
+        size: stats.size,
+        lastModified: stats.mtime.toISOString()
+      };
+
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`Component not found: ${config.componentPath}`);
+      }
+      throw error;
+    }
+  }
+
+  async analyzeDependencyImpact(targetComponent, config) {
+    return await this.dependencyAnalyzer.analyzeDependencyImpact(targetComponent, {
+      depth: config.depth,
+      includeTests: config.includeTests,
+      excludeExternal: config.excludeExternal,
+      modificationType: config.modificationType
+    });
+  }
+
+  async predictChangePropagation(targetComponent, dependencyImpact, config) {
+    return await this.propagationPredictor.predictPropagation(targetComponent, dependencyImpact, {
+      depth: config.depth,
+      modificationType: config.modificationType
+    });
+  }
+
+  async assessModificationRisks(targetComponent, dependencyImpact, propagationAnalysis, config) {
+    return await this.riskAssessment.assessRisks(targetComponent, {
+      dependencyImpact,
+      propagationAnalysis,
+      modificationType: config.modificationType,
+      riskThreshold: config.riskThreshold
+    });
+  }
+
+  async generateImpactReport(targetComponent, analyses, config) {
+    const { dependencyImpact, propagationAnalysis, riskAssessment } = analyses;
+
+    const report = {
+      reportId: `impact-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`,
+      timestamp: new Date().toISOString(),
+      targetComponent: {
+        path: targetComponent.path,
+        type: targetComponent.type,
+        size: targetComponent.size
+      },
+      modificationType: config.modificationType,
+      analysisDepth: config.depth,
+      summary: {
+        overallRisk: riskAssessment.overallRisk,
+        affectedComponents: dependencyImpact.affectedComponents.length,
+        propagationDepth: propagationAnalysis.maxDepth,
+        criticalIssues: riskAssessment.criticalIssues.length,
+        recommendations: riskAssessment.recommendations.length
+      },
+      dependencyAnalysis: dependencyImpact,
+      propagationAnalysis: propagationAnalysis,
+      riskAssessment: riskAssessment,
+      metadata: {
+        analysisTimestamp: new Date().toISOString(),
+        configUsed: config
+      }
+    };
+
+    return report;
+  }
+
+  async displayImpactSummary(report) {
+    console.log(chalk.blue('\\n📊 Impact Analysis Results'));
+    console.log(chalk.gray('━'.repeat(50)));
+    
+    console.log(`Target: ${chalk.white(report.targetComponent.path)}`);
+    console.log(`Modification: ${chalk.white(report.modificationType)}`);
+    console.log(`Risk Level: ${this.formatRiskLevel(report.summary.overallRisk)}`);
+    console.log(`Affected Components: ${chalk.white(report.summary.affectedComponents)}`);
+    console.log(`Propagation Depth: ${chalk.white(report.summary.propagationDepth)}`);
+
+    if (report.summary.criticalIssues > 0) {
+      console.log(`${chalk.red('⚠ Critical Issues:')} ${report.summary.criticalIssues}`);
+    }
+
+    if (report.riskAssessment.recommendations.length > 0) {
+      console.log(chalk.blue('\\n💡 Key Recommendations:'));
+      report.riskAssessment.recommendations.slice(0, 3).forEach((rec, index) => {
+        console.log(`  ${index + 1}. ${rec.title}`);
+      });
+    }
+
+    // Display most critical affected components
+    if (report.dependencyAnalysis.affectedComponents.length > 0) {
+      console.log(chalk.blue('\\n🔗 Most Impacted Components:'));
+      const topImpacted = report.dependencyAnalysis.affectedComponents
+        .sort((a, b) => b.impactScore - a.impactScore)
+        .slice(0, 5);
+      
+      topImpacted.forEach(component => {
+        const riskIcon = component.impactScore > 8 ? '🔴' : component.impactScore > 5 ? '🟡' : '🟢';
+        console.log(`  ${riskIcon} ${component.path} (impact: ${component.impactScore}/10)`);
+      });
+    }
+  }
+
+  async generateVisualRepresentation(report, config) {
+    const visualData = await this.visualGenerator.generateImpactVisualization(report, {
+      format: config.outputFormat,
+      includeInteractive: config.outputFormat === 'html'
+    });
+
+    if (config.outputFormat === 'visual') {
+      // Display ASCII-based visual representation
+      console.log(chalk.blue('\\n📈 Visual Impact Map:'));
+      console.log(visualData.asciiGraph);
+    }
+
+    return visualData;
+  }
+
+  async saveDetailedReport(report, savePath, format) {
+    const fullPath = path.resolve(this.rootPath, savePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+
+    let content;
+    switch (format) {
+      case 'json':
+        content = JSON.stringify(report, null, 2);
+        break;
+      case 'html':
+        content = await this.generateHtmlReport(report);
+        break;
+      default:
+        content = await this.generateTextReport(report);
+    }
+
+    await fs.writeFile(fullPath, content);
+    console.log(chalk.green(`\\n📄 Detailed report saved to: ${savePath}`));
+  }
+
+  async handleHighRiskApproval(report) {
+    console.log(chalk.yellow('\\n⚠ HIGH RISK MODIFICATION DETECTED'));
+    console.log(chalk.gray('This modification may have significant impact on the framework.\\n'));
+
+    const { approved } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'approved',
+      message: `Proceed with ${report.summary.overallRisk} risk modification of ${report.targetComponent.path}?`,
+      default: false
+    }]);
+
+    if (approved) {
+      // Log approval for audit trail
+      await this.approvalWorkflow.logApproval(report, {
+        approvedBy: 'user',
+        approvalTimestamp: new Date().toISOString(),
+        riskLevel: report.summary.overallRisk
+      });
+    }
+
+    return approved;
+  }
+
+  // Helper methods
+
+  determineComponentType(filePath, content) {
+    if (filePath.includes('/agents/')) return 'agent';
+    if (filePath.includes('/tasks/')) return 'task';
+    if (filePath.includes('/workflows/')) return 'workflow';
+    if (filePath.includes('/utils/')) return 'util';
+    
+    // Analyze content for type hints
+    if (content.includes('class') && content.includes('execute')) return 'task';
+    if (content.includes('agent_name') || content.includes('Agent')) return 'agent';
+    if (content.includes('workflow_steps') || content.includes('Workflow')) return 'workflow';
+    
+    return 'unknown';
+  }
+
+  formatRiskLevel(riskLevel) {
+    const colors = {
+      low: chalk.green,
+      medium: chalk.yellow,
+      high: chalk.red,
+      critical: chalk.red.bold
+    };
+    return colors[riskLevel] ? colors[riskLevel](riskLevel.toUpperCase()) : riskLevel;
+  }
+
+  async generateHtmlReport(report) {
+    // Generate comprehensive HTML report with charts and interactivity
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <title>Impact Analysis Report - ${report.targetComponent.path}</title>
+    <style>
+        body { font-family: Arial, sans-serif; margin: 20px; }
+        .risk-${report.summary.overallRisk} { color: ${this.getRiskColor(report.summary.overallRisk)}; }
+        .component-list { margin: 10px 0; }
+        .component-item { padding: 5px; margin: 2px 0; border-left: 3px solid #ccc; }
+        .chart-container { margin: 20px 0; }
+    </style>
+</head>
+<body>
+    <h1>Impact Analysis Report</h1>
+    <h2>Target: ${report.targetComponent.path}</h2>
+    <p><strong>Risk Level:</strong> <span class="risk-${report.summary.overallRisk}">${report.summary.overallRisk.toUpperCase()}</span></p>
+    <p><strong>Affected Components:</strong> ${report.summary.affectedComponents}</p>
+    <p><strong>Analysis Date:</strong> ${report.timestamp}</p>
+    
+    <h3>Dependency Impact</h3>
+    <div class="component-list">
+        ${report.dependencyAnalysis.affectedComponents.map(comp => 
+          `<div class="component-item">
+             <strong>${comp.path}</strong> (Impact: ${comp.impactScore}/10)
+             <br><small>${comp.reason}</small>
+           </div>`
+        ).join('')}
+    </div>
+    
+    <h3>Risk Assessment</h3>
+    <ul>
+        ${report.riskAssessment.recommendations.map(rec => 
+          `<li><strong>${rec.title}</strong><br>${rec.description}</li>`
+        ).join('')}
+    </ul>
+</body>
+</html>`;
+  }
+
+  async generateTextReport(report) {
+    return `
+IMPACT ANALYSIS REPORT
+=====================
+
+Target Component: ${report.targetComponent.path}
+Modification Type: ${report.modificationType}
+Analysis Depth: ${report.analysisDepth}
+Risk Level: ${report.summary.overallRisk.toUpperCase()}
+Analysis Date: ${report.timestamp}
+
+SUMMARY
+-------
+Affected Components: ${report.summary.affectedComponents}
+Propagation Depth: ${report.summary.propagationDepth}
+Critical Issues: ${report.summary.criticalIssues}
+Recommendations: ${report.summary.recommendations}
+
+AFFECTED COMPONENTS
+------------------
+${report.dependencyAnalysis.affectedComponents.map(comp => 
+  `- ${comp.path} (Impact: ${comp.impactScore}/10)
+    Reason: ${comp.reason}`
+).join('\\n')}
+
+RECOMMENDATIONS
+--------------
+${report.riskAssessment.recommendations.map((rec, index) => 
+  `${index + 1}. ${rec.title}
+     ${rec.description}`
+).join('\\n\\n')}
+
+RISK FACTORS
+-----------
+${report.riskAssessment.riskFactors.map(factor => 
+  `- ${factor.type}: ${factor.description} (Severity: ${factor.severity})`
+).join('\\n')}
+`;
+  }
+
+  getRiskColor(riskLevel) {
+    const colors = {
+      low: '#28a745',
+      medium: '#ffc107', 
+      high: '#dc3545',
+      critical: '#721c24'
+    };
+    return colors[riskLevel] || '#6c757d';
+  }
+}
+
+module.exports = AnalyzeImpactTask;
+```
+
+## Validation Rules
+
+### Input Validation
+- Modification type must be valid (modify, deprecate, remove, refactor)
+- Component path must exist and be accessible
+- Analysis depth must be recognized level
+- Risk threshold must be valid level
+
+### Safety Checks
+- High-risk modifications require approval workflow
+- Critical modifications generate detailed warnings
+- External dependency analysis can be excluded for security
+- Report generation validates output paths
+
+### Analysis Requirements
+- Dependency analysis must trace all connections
+- Risk assessment must consider modification type
+- Propagation prediction must respect analysis depth
+- Visual representation must be accessible
+
+## Integration Points
+
+### Dependency Impact Analyzer
+- Analyzes component dependencies and reverse dependencies
+- Calculates impact scores for affected components
+- Traces dependency chains to specified depth
+- Identifies breaking change potential
+
+### Change Propagation Predictor
+- Predicts how changes will propagate through the system
+- Models cascading effects of modifications
+- Estimates propagation depth and scope
+- Identifies potential bottlenecks and failure points
+
+### Risk Assessment System
+- Evaluates modification risks across multiple dimensions
+- Considers component criticality and usage patterns
+- Generates actionable recommendations
+- Provides risk mitigation strategies
+
+### Visual Impact Generator
+- Creates visual representations of impact analysis
+- Supports multiple output formats (ASCII, HTML, JSON)
+- Generates interactive impact maps for complex scenarios
+- Provides exportable reports and visualizations
+
+### Approval Workflow
+- Manages approval process for high-risk modifications
+- Maintains audit trail of approval decisions
+- Integrates with user approval prompts
+- Supports automated approval rules for trusted scenarios
+
+## Output Structure
+
+### Success Response
+```json
+{
+  "success": true,
+  "targetComponent": "grimoire/agents/weather-agent.md",
+  "riskLevel": "medium",
+  "affectedComponents": 12,
+  "propagationDepth": 3,
+  "requiresApproval": false,
+  "impactReport": {
+    "summary": { ... },
+    "dependencyAnalysis": { ... },
+    "riskAssessment": { ... }
+  }
+}
+```
+
+### High-Risk Response
+```json
+{
+  "success": true,
+  "requiresApproval": true,
+  "riskLevel": "high",
+  "impactSummary": {
+    "criticalIssues": 3,
+    "affectedComponents": 25,
+    "recommendations": 8
+  }
+}
+```
+
+## Security Considerations
+- Validate all file paths to prevent directory traversal
+- Sanitize component paths and modification descriptions
+- Ensure approval workflow cannot be bypassed for critical changes
+- Validate output file paths for report generation
+- Log all high-risk modification attempts for audit 
+