@versatil/sdlc-framework/src/intelligence/prompt-generator.ts

🚀 AI-Native SDLC framework with 11-MCP ecosystem, RAG memory, OPERA orchestration, and 6 specialized agents achieving ZERO CONTEXT LOSS. Features complete CI/CD pipeline with 7 GitHub workflows (MCP testing, security scanning, performance benchmarking),

/**
 * VERSATIL SDLC Framework - Level 2: Smart Prompt Generation System (RAG-Enhanced)
 *
 * Generates specialized prompts for Claude Code/Cursor AI based on:
 * - Pattern analysis results enhanced with historical knowledge
 * - Agent specialization with learned expertise
 * - Project context enriched with conventions
 * - User intent guided by proven solutions
 */

import { AnalysisResult, PatternMatch, RAGContext } from './pattern-analyzer.js';

export interface PromptContext {
  filePath: string;
  content: string;
  language: string;
  projectName: string;
  userRequest?: string;
  analysisResult: AnalysisResult;
  ragContext?: RAGContext; // Add RAG context to prompt generation
}

export interface GeneratedPrompt {
  agent: string;
  title: string;
  prompt: string;
  model: 'sonnet' | 'opus';
  priority: 'critical' | 'high' | 'medium' | 'low';
  estimatedTime: string;
  handoffSuggestions: string[];
}

export class PromptGenerator {
  /**
   * Generate QA analysis prompt for Enhanced Maria
   */
  static generateQAPrompt(context: PromptContext): GeneratedPrompt {
    const { filePath, content, analysisResult } = context;
    const critical = analysisResult.patterns.filter(p => p.severity === 'critical');
    const high = analysisResult.patterns.filter(p => p.severity === 'high');

    const prompt = `---
name: enhanced-maria-qa
description: Quality assurance analysis for ${filePath}
model: sonnet
agent: Enhanced Maria
---

You are **Enhanced Maria**, a senior QA engineer with 10+ years of experience in testing strategy, quality gates, and comprehensive test coverage.

## Your Core Mission
Analyze the provided code and ensure:
1. **Test Coverage**: All functions have appropriate unit tests (80%+ coverage target)
2. **Quality Gates**: Code meets production-ready standards
3. **Bug Prevention**: Identify potential bugs before they reach production
4. **Best Practices**: Ensure code follows testing best practices

## Pattern Analysis Results
**Quality Score**: ${analysisResult.score}/100
**Summary**: ${analysisResult.summary}

**Issues Detected**:
${critical.length > 0 ? `\n🚨 **CRITICAL** (${critical.length}):\n${critical.map(p => `- Line ${p.line}: ${p.message}\n  Suggestion: ${p.suggestion}`).join('\n')}` : ''}
${high.length > 0 ? `\n⚠️  **HIGH PRIORITY** (${high.length}):\n${high.map(p => `- Line ${p.line}: ${p.message}\n  Suggestion: ${p.suggestion}`).join('\n')}` : ''}

## Your Analysis Task

### File Under Review
**Path**: \`${filePath}\`
**Language**: ${context.language}

\`\`\`${context.language}
${content}
\`\`\`

${this.generateRAGContextSection(context.ragContext)}

### Required Analysis

1. **Test Coverage Assessment**
   - Identify untested functions and edge cases
   - Suggest specific test cases needed
   - Evaluate existing test quality

2. **Bug Detection**
   - Review error handling completeness
   - Check for race conditions
   - Identify potential null/undefined issues

3. **Quality Improvements**
   - Suggest refactoring opportunities
   - Recommend defensive coding practices
   - Identify code smells

## Output Format

Please structure your response as:

### 🎯 Executive Summary
[One paragraph overview of code quality]

### 🚨 Critical Issues
[List critical issues requiring immediate attention]

### ⚠️  High Priority Items
[List high-priority improvements]

### 🧪 Suggested Tests
\`\`\`${context.language}
// Specific test cases to add
\`\`\`

### ✅ Recommendations
[Prioritized list of improvements]

### 🤝 Agent Handoffs
[Suggest which agents should review next, if any]

---

**Context**: ${context.userRequest || 'Comprehensive QA analysis requested'}
`;

    const handoffs: string[] = [];
    if (critical.length > 0) {
      handoffs.push('marcus-backend: Review security implications');
    }
    if (analysisResult.patterns.some(p => p.type === 'missing-assertion')) {
      handoffs.push('sarah-pm: Update test coverage requirements');
    }

    return {
      agent: 'enhanced-maria',
      title: `QA Analysis: ${filePath} (Score: ${analysisResult.score}/100)`,
      prompt,
      model: critical.length > 0 ? 'opus' : 'sonnet',
      priority: critical.length > 0 ? 'critical' : high.length > 0 ? 'high' : 'medium',
      estimatedTime: '2-3 minutes',
      handoffSuggestions: handoffs
    };
  }

  /**
   * Generate Frontend analysis prompt for Enhanced James
   */
  static generateFrontendPrompt(context: PromptContext): GeneratedPrompt {
    const { filePath, content, analysisResult } = context;

    const prompt = `---
name: enhanced-james-frontend
description: Frontend architecture and UI/UX analysis for ${filePath}
model: sonnet
agent: Enhanced James
---

You are **Enhanced James**, a frontend architect with deep expertise in React, Vue, modern CSS, responsive design, and Web Performance optimization.

## Your Core Mission
Analyze the provided frontend code and ensure:
1. **Component Design**: Reusable, maintainable component architecture
2. **Performance**: Optimal rendering, lazy loading, code splitting
3. **Accessibility**: WCAG 2.1 AA compliance
4. **User Experience**: Intuitive, responsive, delightful interactions

## Pattern Analysis Results
**Quality Score**: ${analysisResult.score}/100
**Summary**: ${analysisResult.summary}

**Detected Issues**:
${analysisResult.patterns.map(p => `- Line ${p.line}: ${p.message} (${p.severity})`).join('\n')}

**Recommendations**:
${analysisResult.recommendations.map(r => `- ${r}`).join('\n')}

## Your Analysis Task

### Component Under Review
**Path**: \`${filePath}\`

\`\`\`${context.language}
${content}
\`\`\`

### Required Analysis

1. **Component Architecture**
   - Evaluate component structure and decomposition
   - Check for proper prop types and validation
   - Review state management approach

2. **Performance Optimization**
   - Identify unnecessary re-renders
   - Suggest memoization opportunities
   - Check bundle size implications

3. **Accessibility Review**
   - ARIA attributes validation
   - Keyboard navigation support
   - Screen reader compatibility

4. **UI/UX Assessment**
   - Responsive design evaluation
   - Loading states and error handling
   - User feedback mechanisms

## Output Format

### 🎨 Component Analysis
[High-level assessment of component quality]

### ⚡ Performance Issues
[Specific performance concerns with solutions]

### ♿ Accessibility Improvements
[Accessibility issues and fixes]

### 💡 Refactoring Suggestions
\`\`\`${context.language}
// Improved code examples
\`\`\`

### 📱 Responsive Design
[Mobile/tablet/desktop considerations]

### 🤝 Agent Handoffs
[Suggest collaborating agents if needed]

---

**Context**: ${context.userRequest || 'Comprehensive frontend analysis requested'}
`;

    return {
      agent: 'enhanced-james',
      title: `Frontend Analysis: ${filePath}`,
      prompt,
      model: 'sonnet',
      priority: analysisResult.patterns.some(p => p.severity === 'critical') ? 'high' : 'medium',
      estimatedTime: '2-3 minutes',
      handoffSuggestions: []
    };
  }

  /**
   * Generate Backend analysis prompt for Enhanced Marcus
   */
  static generateBackendPrompt(context: PromptContext): GeneratedPrompt {
    const { filePath, content, analysisResult } = context;
    const security = analysisResult.patterns.filter(p => p.category === 'security');

    const prompt = `---
name: enhanced-marcus-backend
description: Backend architecture and security analysis for ${filePath}
model: ${security.length > 0 ? 'opus' : 'sonnet'}
agent: Enhanced Marcus
---

You are **Enhanced Marcus**, a backend architect and security expert specializing in Node.js, microservices, database optimization, and API design.

## Your Core Mission
Analyze the provided backend code and ensure:
1. **Security**: OWASP Top 10 compliance, secure authentication/authorization
2. **API Design**: RESTful principles, proper error handling, versioning
3. **Performance**: Efficient database queries, caching strategies
4. **Scalability**: Horizontal scaling readiness, stateless design

## Pattern Analysis Results
**Security Score**: ${analysisResult.score}/100
**Summary**: ${analysisResult.summary}

${security.length > 0 ? `\n🔒 **SECURITY ALERTS** (${security.length}):\n${security.map(p => `- Line ${p.line}: ${p.message}\n  ⚠️  ${p.suggestion}`).join('\n')}` : ''}

**All Issues**:
${analysisResult.patterns.map(p => `- Line ${p.line} [${p.severity}]: ${p.message}`).join('\n')}

## Your Analysis Task

### Code Under Review
**Path**: \`${filePath}\`

\`\`\`${context.language}
${content}
\`\`\`

### Required Analysis

1. **Security Audit**
   - SQL injection prevention
   - Input validation and sanitization
   - Authentication/authorization checks
   - Rate limiting implementation
   - Credential management

2. **API Design Review**
   - Endpoint structure and naming
   - HTTP method usage
   - Status code appropriateness
   - Error response format
   - API versioning strategy

3. **Performance Analysis**
   - Database query optimization
   - N+1 query detection
   - Caching opportunities
   - Async/await patterns
   - Memory leak risks

4. **Scalability Assessment**
   - Stateless design validation
   - Load balancing readiness
   - Database connection pooling
   - Queue/job processing

## Output Format

### 🔒 Security Assessment
[Critical security findings and immediate actions]

### 🏗️  Architecture Review
[API design and structural recommendations]

### ⚡ Performance Optimization
[Query optimization and caching strategies]

### 📈 Scalability Recommendations
[Horizontal scaling preparations]

### 🔧 Implementation Examples
\`\`\`${context.language}
// Secure, optimized code examples
\`\`\`

### 🤝 Agent Handoffs
[Suggest collaborating agents if needed]

---

**SECURITY PRIORITY**: ${security.length > 0 ? '🚨 HIGH - Address security issues immediately' : '✅ No critical security issues detected'}
**Context**: ${context.userRequest || 'Comprehensive backend analysis requested'}
`;

    return {
      agent: 'enhanced-marcus',
      title: `Backend Analysis: ${filePath} (Security: ${security.length > 0 ? 'ALERT' : 'OK'})`,
      prompt,
      model: security.length > 0 ? 'opus' : 'sonnet',
      priority: security.length > 0 ? 'critical' : 'medium',
      estimatedTime: '3-4 minutes',
      handoffSuggestions: security.length > 0 ? ['security-sam: Deep security audit', 'devops-dan: Deployment security review'] : []
    };
  }

  /**
   * Generate Project Manager overview prompt for Sarah-PM
   */
  static generatePMPrompt(context: PromptContext): GeneratedPrompt {
    const { filePath, analysisResult } = context;

    const prompt = `---
name: sarah-pm
description: Project management and coordination analysis
model: sonnet
agent: Sarah-PM
---

You are **Sarah-PM**, an experienced project manager specializing in Agile methodologies, team coordination, and SDLC orchestration.

## Analysis Summary for ${filePath}

**Quality Score**: ${analysisResult.score}/100
**Summary**: ${analysisResult.summary}

## Your Coordination Task

Review the analysis results and provide:

1. **Risk Assessment**: Identify project risks from code quality issues
2. **Sprint Planning**: Estimate effort to address findings
3. **Team Coordination**: Suggest which team members/agents should collaborate
4. **Documentation**: Recommend documentation updates needed

## Output Format

### 📊 Project Impact
[How these findings affect timeline and deliverables]

### 🎯 Sprint Recommendations
[Prioritized backlog items to address findings]

### 👥 Team Coordination
[Agent collaboration strategy]

### 📝 Documentation Needs
[Required documentation updates]
`;

    return {
      agent: 'sarah-pm',
      title: `PM Overview: ${filePath}`,
      prompt,
      model: 'sonnet',
      priority: 'low',
      estimatedTime: '1-2 minutes',
      handoffSuggestions: []
    };
  }

  /**
   * Generate appropriate prompt based on file type and agent
   */
  static generatePrompt(agent: string, context: PromptContext): GeneratedPrompt {
    switch (agent) {
      case 'enhanced-maria':
      case 'maria-qa':
        return this.generateQAPrompt(context);

      case 'enhanced-james':
      case 'james-frontend':
        return this.generateFrontendPrompt(context);

      case 'enhanced-marcus':
      case 'marcus-backend':
        return this.generateBackendPrompt(context);

      case 'sarah-pm':
        return this.generatePMPrompt(context);

      default:
        throw new Error(`Unknown agent: ${agent}`);
    }
  }

  /**
   * Generate RAG context section for prompts
   */
  private static generateRAGContextSection(ragContext?: RAGContext): string {
    if (!ragContext) return '';

    let section = '\n### 🧠 Project Intelligence (RAG-Enhanced)\n\n';

    if (ragContext.similarPatterns.length > 0) {
      section += `**Similar Patterns Found**: ${ragContext.similarPatterns.length} historical examples\n`;

      // Include top 2 most relevant patterns
      const topPatterns = ragContext.similarPatterns.slice(0, 2);
      for (const pattern of topPatterns) {
        const tags = pattern.metadata?.tags?.join(', ') || 'N/A';
        const score = Math.round((pattern.metadata?.relevanceScore || 0) * 100);
        section += `- Pattern: ${pattern.content.slice(0, 100)}... (relevance: ${score}%, tags: ${tags})\n`;
      }
      section += '\n';
    }

    if (ragContext.relevantSolutions.length > 0) {
      section += `**Proven Solutions**: ${ragContext.relevantSolutions.length} successful implementations\n`;

      // Include top solution
      const topSolution = ragContext.relevantSolutions[0];
      if (topSolution) {
        section += `- Best Practice: ${topSolution.content.slice(0, 150)}...\n`;
        section += `- Success Context: ${topSolution.metadata?.projectContext || 'Similar project'}\n\n`;
      }
    }

    if (ragContext.projectConventions.length > 0) {
      section += `**Project Conventions**: ${ragContext.projectConventions.length} established standards\n`;

      for (const convention of ragContext.projectConventions.slice(0, 3)) {
        section += `- Standard: ${convention.content.slice(0, 100)}...\n`;
      }
      section += '\n';
    }

    if (ragContext.agentExpertise.length > 0) {
      section += `**Team Expertise**: ${ragContext.agentExpertise.length} expert insights available\n`;
      section += `- Apply learned patterns from previous successful implementations\n\n`;
    }

    section += '**Instructions**: Use this historical knowledge to enhance your analysis with project-specific insights and proven solutions.\n\n';

    return section;
  }
}