@boundless-oss/atlas/src/prompts/few-shot-examples.ts

Atlas - MCP Server for comprehensive startup project management

/**
 * Few-Shot Prompting Examples
 * Implements MCP Design Guide Section 3.2 principles for guided tool selection
 */

export interface ToolSelectionExample {
  userRequest: string;
  context?: string;
  correctToolCall: {
    tool: string;
    parameters: Record<string, any>;
  };
  reasoning: string;
  commonMistakes?: string[];
}

export interface ExampleCategory {
  category: string;
  description: string;
  examples: ToolSelectionExample[];
}

/**
 * Comprehensive few-shot examples for tool selection guidance
 */
export const TOOL_SELECTION_EXAMPLES: ExampleCategory[] = [
  {
    category: 'Project Management',
    description: 'Examples for project initialization and management tasks',
    examples: [
      {
        userRequest: 'I want to start a new project for a SaaS application with user management',
        correctToolCall: {
          tool: 'initialize_atlas_project',
          parameters: {
            projectName: 'user-management-saas',
            projectType: 'saas',
            includeClaudeConfig: true
          }
        },
        reasoning: 'Project initialization is the first step for any new project. The tool sets up the Atlas marker file and basic configuration.',
        commonMistakes: [
          'Using create_kanban_board first without project initialization',
          'Using create_agile_sprint without setting up the project structure'
        ]
      },
      {
        userRequest: 'Check if this directory is already set up as an Atlas project',
        correctToolCall: {
          tool: 'check_project_status',
          parameters: {}
        },
        reasoning: 'Before doing any project operations, check if Atlas is already initialized to avoid conflicts.',
        commonMistakes: [
          'Assuming the project is not initialized and running init commands',
          'Using find_atlas_project when a simple status check is needed'
        ]
      }
    ]
  },

  {
    category: 'Agile Planning',
    description: 'Examples for agile methodology and sprint planning',
    examples: [
      {
        userRequest: 'I need to plan a 2-week sprint for implementing user authentication',
        context: 'Project already has a backlog with user stories',
        correctToolCall: {
          tool: 'create_sprint_interactive',
          parameters: {
            action: 'start'
          }
        },
        reasoning: 'Interactive sprint creation guides through proper capacity planning and story selection, ensuring comprehensive sprint setup.',
        commonMistakes: [
          'Using create_agile_sprint without proper planning',
          'Starting with add_story before creating the sprint structure'
        ]
      },
      {
        userRequest: 'Add a user story: As a user, I want to reset my password so I can regain access to my account',
        correctToolCall: {
          tool: 'add_story',
          parameters: {
            title: 'Password Reset Functionality',
            description: 'As a user, I want to reset my password so I can regain access to my account',
            storyPoints: 5,
            priority: 'high',
            acceptanceCriteria: [
              'User can request password reset via email',
              'Reset link expires after 24 hours',
              'New password must meet security requirements',
              'User receives confirmation after successful reset'
            ]
          }
        },
        reasoning: 'User stories should be well-formed with clear acceptance criteria and appropriate story point estimates.',
        commonMistakes: [
          'Not including acceptance criteria',
          'Using unclear or overly technical story titles',
          'Estimating without considering complexity properly'
        ]
      },
      {
        userRequest: 'Create an epic for the entire user management system',
        correctToolCall: {
          tool: 'create_epic_interactive',
          parameters: {
            action: 'start'
          }
        },
        reasoning: 'Interactive epic creation ensures comprehensive business context, success criteria, and planning considerations are captured.',
        commonMistakes: [
          'Using simple create_epic without considering business value',
          'Creating epics that are too small or too large',
          'Not defining clear success criteria'
        ]
      }
    ]
  },

  {
    category: 'Kanban Management',
    description: 'Examples for visual task management with Kanban boards',
    examples: [
      {
        userRequest: 'Set up a Kanban board for our development team workflow',
        correctToolCall: {
          tool: 'create_board_interactive',
          parameters: {
            action: 'start'
          }
        },
        reasoning: 'Interactive board creation helps design the optimal workflow for the specific team and project needs.',
        commonMistakes: [
          'Using generic create_kanban_board without considering team workflow',
          'Creating boards before understanding the process flow'
        ]
      },
      {
        userRequest: 'Add a bug fix task to the development board',
        correctToolCall: {
          tool: 'add_kanban_task',
          parameters: {
            boardName: 'Development',
            title: 'Fix login validation bug',
            description: 'Users are able to login with invalid email formats, bypassing client-side validation',
            column: 'Backlog',
            priority: 'high',
            tags: ['bug', 'security', 'frontend']
          }
        },
        reasoning: 'Bugs should be clearly described with steps to reproduce and appropriate priority and tags for filtering.',
        commonMistakes: [
          'Not specifying the board name',
          'Using vague descriptions',
          'Not setting appropriate priority for bugs'
        ]
      },
      {
        userRequest: 'Move the authentication task from "In Progress" to "Review"',
        correctToolCall: {
          tool: 'move_kanban_task',
          parameters: {
            boardName: 'Development',
            taskId: 'auth-task-123',
            column: 'Review'
          }
        },
        reasoning: 'Task movement reflects workflow progression and requires specific task identification.',
        commonMistakes: [
          'Not providing the correct task ID',
          'Moving to non-existent columns',
          'Forgetting to specify the board name'
        ]
      }
    ]
  },

  {
    category: 'Development Workflow',
    description: 'Examples for TDD and development process management',
    examples: [
      {
        userRequest: 'I want to implement a new feature for user profile updates',
        correctToolCall: {
          tool: 'start_tdd_session',
          parameters: {
            featureName: 'User Profile Updates',
            description: 'Allow users to update their profile information including name, email, and avatar'
          }
        },
        reasoning: 'TDD sessions ensure proper test-first development and enforce the red-green-refactor cycle.',
        commonMistakes: [
          'Starting with create_feature instead of TDD session',
          'Writing implementation code before tests',
          'Not following the TDD cycle'
        ]
      },
      {
        userRequest: 'Check if I am following TDD properly in my current work',
        correctToolCall: {
          tool: 'check_tdd_status',
          parameters: {}
        },
        reasoning: 'Regular TDD status checks ensure compliance with test-driven development practices.',
        commonMistakes: [
          'Assuming TDD compliance without checking',
          'Running tests instead of checking TDD workflow status'
        ]
      },
      {
        userRequest: 'Run all tests to make sure my changes don\'t break anything',
        correctToolCall: {
          tool: 'run_tests',
          parameters: {
            scope: 'all',
            coverage: true
          }
        },
        reasoning: 'Comprehensive test runs ensure no regressions and provide coverage feedback.',
        commonMistakes: [
          'Running only unit tests when integration tests are needed',
          'Not checking test coverage',
          'Skipping tests before committing changes'
        ]
      }
    ]
  },

  {
    category: 'Memory and Context',
    description: 'Examples for managing project knowledge and context',
    examples: [
      {
        userRequest: 'Remember that we decided to use JWT tokens for authentication',
        correctToolCall: {
          tool: 'store_memory',
          parameters: {
            content: 'Authentication decision: Use JWT tokens for stateless authentication, with refresh token rotation for security',
            type: 'architecture-decision',
            tags: ['authentication', 'jwt', 'security', 'architecture']
          }
        },
        reasoning: 'Important decisions should be stored with appropriate tags for future retrieval and context.',
        commonMistakes: [
          'Not tagging memories appropriately',
          'Storing too little context',
          'Not categorizing the memory type'
        ]
      },
      {
        userRequest: 'What authentication approach did we decide on for this project?',
        correctToolCall: {
          tool: 'search_memories',
          parameters: {
            query: 'authentication decision JWT',
            tags: ['authentication', 'architecture'],
            limit: 5
          }
        },
        reasoning: 'Memory search should use relevant keywords and tags to find architectural decisions.',
        commonMistakes: [
          'Using too broad search terms',
          'Not using tags to filter results',
          'Not providing enough context in the query'
        ]
      }
    ]
  },

  {
    category: 'Security Operations',
    description: 'Examples for security scanning and vulnerability management',
    examples: [
      {
        userRequest: 'Scan the codebase for potential security vulnerabilities',
        correctToolCall: {
          tool: 'perform_security_scan',
          parameters: {
            scope: 'full',
            includeVulnerabilities: true,
            includeDependencies: true
          }
        },
        reasoning: 'Comprehensive security scans should check both code vulnerabilities and dependency issues.',
        commonMistakes: [
          'Only scanning code without checking dependencies',
          'Not including vulnerability databases',
          'Running superficial scans'
        ]
      },
      {
        userRequest: 'Check if we have any hardcoded secrets in our code',
        correctToolCall: {
          tool: 'scan_for_secrets',
          parameters: {
            scope: 'all-files',
            includeComments: true,
            checkHistory: false
          }
        },
        reasoning: 'Secret scanning should be comprehensive but focused on current state rather than git history for performance.',
        commonMistakes: [
          'Not scanning comments where secrets might be left',
          'Scanning git history unnecessarily',
          'Not checking configuration files'
        ]
      }
    ]
  }
];

/**
 * Get relevant examples for a specific tool or category
 */
export function getExamplesForTool(toolName: string): ToolSelectionExample[] {
  const allExamples = TOOL_SELECTION_EXAMPLES.flatMap(category => category.examples);
  return allExamples.filter(example => example.correctToolCall.tool === toolName);
}

/**
 * Get examples for a category
 */
export function getExamplesForCategory(categoryName: string): ToolSelectionExample[] {
  const category = TOOL_SELECTION_EXAMPLES.find(cat => cat.category === categoryName);
  return category ? category.examples : [];
}

/**
 * Find the most relevant examples based on user request keywords
 */
export function findRelevantExamples(
  userRequest: string,
  maxExamples: number = 3
): ToolSelectionExample[] {
  const allExamples = TOOL_SELECTION_EXAMPLES.flatMap(category => category.examples);
  const keywords = userRequest.toLowerCase().split(/\s+/);

  // Score examples based on keyword matches
  const scoredExamples = allExamples.map(example => {
    let score = 0;
    const exampleText = (example.userRequest + ' ' + example.reasoning).toLowerCase();
    
    keywords.forEach(keyword => {
      if (exampleText.includes(keyword)) {
        score += 1;
      }
    });

    return { example, score };
  });

  // Return top examples sorted by score
  return scoredExamples
    .filter(item => item.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, maxExamples)
    .map(item => item.example);
}

/**
 * Format examples for inclusion in prompts
 */
export function formatExamplesForPrompt(examples: ToolSelectionExample[]): string {
  if (examples.length === 0) {
    return '';
  }

  let formatted = '**Examples of Correct Tool Usage:**\n\n';
  
  examples.forEach((example, index) => {
    formatted += `**Example ${index + 1}:**\n`;
    formatted += `User Request: "${example.userRequest}"\n`;
    if (example.context) {
      formatted += `Context: ${example.context}\n`;
    }
    formatted += `Correct Tool Call: \`${example.correctToolCall.tool}\`\n`;
    formatted += `Parameters: \`${JSON.stringify(example.correctToolCall.parameters, null, 2)}\`\n`;
    formatted += `Reasoning: ${example.reasoning}\n`;
    
    if (example.commonMistakes && example.commonMistakes.length > 0) {
      formatted += `Common Mistakes to Avoid:\n`;
      example.commonMistakes.forEach(mistake => {
        formatted += `- ${mistake}\n`;
      });
    }
    formatted += '\n';
  });

  return formatted;
}