analyze_project

The analyze_project tool performs deep requirements analysis using Google's Gemini AI to understand project complexity, identify challenges, and provide strategic recommendations.

Overview

• Purpose: Intelligent requirements analysis and complexity assessment
• AI Model: Gemini 2.0 Flash Thinking (gemini-2.0-flash-thinking-exp-1219)
• Typical Duration: 2-5 seconds
• Source: src/tools/analyzeProject.ts

Input Schema

{
  requirements: string;      // Project requirements or description
  context?: {               // Optional additional context
    existingStack?: string[];     // Current technology stack
    teamSize?: number;            // Team size
    timeline?: string;            // Project timeline
    constraints?: string[];       // Known constraints
    businessDomain?: string;      // Industry/domain
  }
}

Output Format

{
  "success": true,
  "analysis": {
    "summary": "Building a real-time collaborative document editor with advanced features",
    "complexity": {
      "score": 7.5,
      "level": "HIGH",
      "factors": {
        "technical": 8,
        "integration": 7,
        "scalability": 7.5,
        "security": 7
      }
    },
    "keyComponents": [
      {
        "name": "Real-time Sync Engine",
        "complexity": 9,
        "description": "WebSocket-based synchronization with conflict resolution"
      },
      {
        "name": "Authentication System",
        "complexity": 6,
        "description": "Multi-tenant auth with role-based permissions"
      }
    ],
    "challenges": [
      {
        "area": "Conflict Resolution",
        "severity": "HIGH",
        "description": "Handling simultaneous edits from multiple users",
        "mitigation": "Implement CRDT or operational transformation"
      }
    ],
    "recommendations": {
      "architecture": "Microservices with event sourcing",
      "technologies": ["Node.js", "Redis", "PostgreSQL", "WebSockets"],
      "patterns": ["CQRS", "Event Sourcing", "Pub/Sub"],
      "approach": "Start with core editing, add collaboration incrementally"
    },
    "risks": [
      {
        "type": "TECHNICAL",
        "description": "Real-time sync complexity",
        "probability": "MEDIUM",
        "impact": "HIGH",
        "mitigation": "Use proven libraries like Yjs or ShareJS"
      }
    ],
    "phases": [
      {
        "phase": 1,
        "name": "Foundation",
        "duration": "2-3 weeks",
        "deliverables": ["Basic editor", "User authentication", "Document storage"]
      },
      {
        "phase": 2,
        "name": "Collaboration",
        "duration": "3-4 weeks",
        "deliverables": ["Real-time sync", "Presence awareness", "Basic permissions"]
      }
    ]
  },
  "metadata": {
    "analysisTime": 3421,
    "modelUsed": "gemini-2.0-flash-thinking-exp-1219",
    "confidence": 0.92
  }
}

Usage Examples

Basic Analysis

// Analyze simple requirements
@mcp__orchestre__analyze_project({
  requirements: "Build an e-commerce platform with payment processing"
})

With Context

// Provide rich context for better analysis
@mcp__orchestre__analyze_project({
  requirements: "Create a real-time analytics dashboard for IoT devices",
  context: {
    existingStack: ["Python", "PostgreSQL", "React"],
    teamSize: 5,
    timeline: "3 months",
    constraints: ["Must handle 1M events/day", "99.9% uptime"],
    businessDomain: "Manufacturing"
  }
})

In Orchestration Workflow

// Used in /orchestrate command
const analysis = await analyze_project({
  requirements: userRequirements
});

if (analysis.complexity.score > 7) {
  // Complex project - needs phased approach
  const plan = await generate_plan({
    requirements: userRequirements,
    analysis: analysis
  });
}

Analysis Components

Complexity Scoring

The tool evaluates complexity across multiple dimensions:

Factor	Description	Weight
Technical	Code complexity, algorithms	30%
Integration	External systems, APIs	25%
Scalability	Performance requirements	25%
Security	Security requirements	20%

Complexity Levels:

• LOW (0-3): Simple CRUD, basic features
• MEDIUM (4-6): Standard applications
• HIGH (7-8): Complex systems
• VERY HIGH (9-10): Cutting-edge, R&D

Key Components Identification

The tool identifies major system components:

{
  "name": "Payment Processing",
  "complexity": 7,
  "description": "Stripe integration with subscription management",
  "dependencies": ["User Management", "Billing Database"],
  "estimatedEffort": "1-2 weeks"
}

Risk Assessment

Comprehensive risk analysis:

{
  "type": "TECHNICAL|BUSINESS|OPERATIONAL",
  "description": "Detailed risk description",
  "probability": "LOW|MEDIUM|HIGH",
  "impact": "LOW|MEDIUM|HIGH|CRITICAL",
  "mitigation": "Recommended mitigation strategy"
}

AI Model Details

Gemini 2.0 Flash Thinking

This tool leverages Gemini's advanced reasoning capabilities:

• Deep Analysis: Understands complex requirements
• Pattern Recognition: Identifies common architectures
• Trade-off Analysis: Weighs different approaches
• Domain Knowledge: Industry-specific insights

Prompt Engineering

The tool uses sophisticated prompts:

const systemPrompt = `You are an expert software architect and project analyst.
Analyze the given requirements and provide:
1. Complexity assessment with numerical scores
2. Key components breakdown
3. Technical challenges and solutions
4. Risk analysis with mitigation strategies
5. Phased implementation approach`;

Advanced Features

Domain-Specific Analysis

The tool adapts to different domains:

• SaaS: Focus on multi-tenancy, billing
• E-commerce: Payment, inventory, scaling
• Real-time: Latency, synchronization
• Enterprise: Integration, compliance

Technology Recommendations

Based on requirements and context:

{
  "primary": ["Next.js", "PostgreSQL"],
  "secondary": ["Redis", "ElasticSearch"],
  "devops": ["Docker", "Kubernetes"],
  "monitoring": ["Datadog", "Sentry"]
}

Pattern Recognition

Identifies applicable patterns:

• Architectural: Microservices, Monolith, Serverless
• Design: CQRS, Event Sourcing, MVC
• Integration: REST, GraphQL, gRPC
• Data: SQL, NoSQL, Time-series

Performance Optimization

Caching Strategy

Results are cached for identical inputs:

const cacheKey = hash({ requirements, context });
if (cache.has(cacheKey)) {
  return cache.get(cacheKey);
}

Request Optimization

• Structured prompts for consistent results
• Minimal token usage
• Parallel processing where possible

Error Handling

Common Errors

Error	Cause	Solution
GEMINI_API_ERROR	API key issues	Check GEMINI_API_KEY
REQUIREMENTS_TOO_VAGUE	Insufficient detail	Provide more specific requirements
ANALYSIS_TIMEOUT	Complex analysis	Break into smaller parts
RATE_LIMIT_EXCEEDED	API quota	Wait or upgrade plan

Error Response

{
  "success": false,
  "error": {
    "code": "GEMINI_API_ERROR",
    "message": "Failed to analyze requirements",
    "details": "Invalid API key or quota exceeded",
    "suggestions": [
      "Check GEMINI_API_KEY environment variable",
      "Verify API quota at console.cloud.google.com"
    ]
  }
}

Best Practices

1. Provide Clear Requirements

Good Requirements:

Build a project management tool with:
- Task tracking with dependencies
- Team collaboration features
- Gantt charts and reporting
- Integration with Slack and GitHub
- Support for 100+ concurrent users

Poor Requirements:

Make a project app

2. Include Relevant Context

Context improves analysis quality:

context: {
  existingStack: ["Ruby on Rails", "PostgreSQL"],
  teamSize: 3,
  timeline: "2 months",
  constraints: ["Must integrate with legacy system"],
  businessDomain: "Healthcare"
}

3. Use Analysis Results

Leverage the analysis throughout development:

// Use complexity score for planning
if (analysis.complexity.score > 7) {
  // Plan for longer timeline
  // Consider more senior developers
  // Add extra testing phases
}

// Use recommendations
const tech = analysis.recommendations.technologies;
// Initialize project with recommended stack

// Address risks early
analysis.risks.forEach(risk => {
  if (risk.probability === 'HIGH') {
    // Implement mitigation in phase 1
  }
});

Integration Examples

With Planning Tool

const analysis = await analyze_project({ requirements });
const plan = await generate_plan({
  requirements,
  analysis,
  preferences: {
    methodology: "agile",
    sprintLength: 2
  }
});

In Review Workflow

// Use analysis to guide review focus
const analysis = await analyze_project({ requirements });
const review = await multi_llm_review({
  code: implementedCode,
  focusAreas: analysis.challenges.map(c => c.area)
});

Limitations

Current Limitations

1. Language: English only currently
2. Context Size: ~10,000 tokens max
3. Domain Coverage: Best for web/mobile apps
4. Real-time Updates: Static analysis only

Workarounds

• Break large requirements into sections
• Provide domain-specific context
• Use multiple analyses for different aspects
• Combine with research tool for unknowns

API Reference

Type Definitions

interface AnalyzeProjectArgs {
  requirements: string;
  context?: {
    existingStack?: string[];
    teamSize?: number;
    timeline?: string;
    constraints?: string[];
    businessDomain?: string;
  };
}

interface ComplexityScore {
  score: number;
  level: 'LOW' | 'MEDIUM' | 'HIGH' | 'VERY_HIGH';
  factors: {
    technical: number;
    integration: number;
    scalability: number;
    security: number;
  };
}

interface AnalysisResult {
  summary: string;
  complexity: ComplexityScore;
  keyComponents: Component[];
  challenges: Challenge[];
  recommendations: Recommendations;
  risks: Risk[];
  phases: Phase[];
}

Related

• /orchestrate command - Primary command using this tool
• generate_plan tool - Uses analysis for planning
• Complexity Guide - Managing complex projects