Codebase Analyzer

Codebase Analyzer

Understand existing codebase patterns and context to inform feature judgement.

Purpose

Before judges evaluate a feature proposal, they need to understand:

• What similar features already exist?
• What's the tech stack and architecture?
• What patterns and conventions are used?
• What files/code would be affected?

This skill provides that context through hybrid search strategy (fast → deep as needed).

Input

interface AnalyzerInput {
  parsedProposal: ParsedProposal;  // From feature-parser
  workingDirectory: string;  // Current project root
}

Key data used from ParsedProposal:

• keywords: For searching similar features
• constraints: Tech stack hints (e.g., "Laravel 12.x")
• requirements.mustHave: Integration points to search for

Strategy: Hybrid Search

Phase 1: Targeted Fast Search (Always runs)

Quick reconnaissance using keywords:

1. Identify Tech Stack:

Search for config/manifest files:
- package.json → Node.js, npm/yarn, frameworks (React, Vue, Express)
- composer.json → PHP, Composer, Laravel/Symfony
- requirements.txt / Pipfile → Python, Django/Flask
- go.mod → Go
- Cargo.toml → Rust
- pom.xml / build.gradle → Java
- Gemfile → Ruby, Rails

Use Glob tool:
- Glob pattern: "**/package.json"
- Glob pattern: "**/composer.json"
- Glob pattern: "**/requirements.txt"
- Glob pattern: "**/go.mod"

Read first match to extract:
- Language & version
- Framework & version
- Key dependencies

2. Find Similar Features:

Use keywords from proposal to search:

Grep for keywords in code:
- Pattern: keywords joined with OR regex
- Example: "notification|notify|alert" if proposal is about notifications
- Output mode: "files_with_matches"
- File types: source code only (js, ts, py, php, go, rs, java, rb)

Example searches based on feature type:
- Notifications: grep "notification|notify|alert|email.*send"
- Authentication: grep "auth|login|session|token|jwt"
- API: grep "api|endpoint|route|controller"
- Database: grep "model|schema|migration|query"

Glob for related file patterns:
- Notifications: "**/*{notif,alert,email}*.{ts,js,py,php}"
- Auth: "**/*{auth,login,session,token}*.{ts,js,py,php}"
- Admin: "**/*{admin,dashboard}*.{ts,js,py,php}"

3. Detect Architecture Patterns:

Common patterns to look for:

**MVC Pattern:**
- Glob: "**/models/**", "**/views/**", "**/controllers/**"
- If found → Architecture: "MVC"

**Service Layer:**
- Glob: "**/services/**", "**/lib/services/**"
- If found → Pattern: "Service Layer"

**Repository Pattern:**
- Glob: "**/repositories/**", "**/repo/**"
- If found → Pattern: "Repository Pattern"

**Clean Architecture:**
- Glob: "**/domain/**", "**/application/**", "**/infrastructure/**"
- If found → Architecture: "Clean Architecture" or "Layered"

**Monorepo:**
- Glob: "**/packages/**" OR "**/apps/**"
- If found → Structure: "Monorepo"

**Framework-specific:**
- Laravel: app/Models, app/Http/Controllers, routes/
- Django: models.py, views.py, urls.py
- Express: routes/, controllers/, middleware/
- Next.js: pages/, app/, components/

4. Identify Testing Strategy:

Glob for test files:
- "**/*.test.{js,ts,jsx,tsx}"
- "**/*.spec.{js,ts,jsx,tsx}"
- "**/test/**"
- "**/tests/**"
- "**/__tests__/**"

Read package.json or composer.json to find test frameworks:
- Jest, Mocha, Vitest, Jasmine → JavaScript
- PHPUnit, Pest → PHP
- pytest, unittest → Python
- Go test → Go

5. Find Integration Points:

Based on requirements, search for existing integrations:

If proposal mentions "User model" or "auth":
- Grep: "User.*model|user.*entity|authentication"
- Glob: "**/User.{ts,js,py,php,go}"
- Glob: "**/models/User.*"

If proposal mentions "database":
- Glob: "**/migrations/**"
- Glob: "**/schema/**"
- Read database config files

If proposal mentions specific services (email, payment, etc):
- Grep: "email.*service|mail.*send"
- Grep: "payment|stripe|paypal"

Phase 1 Duration: 30-60 seconds

Phase 2: Deep Analysis (Conditional)

Trigger Deep Analysis if:

• Phase 1 found < 3 relevant files
• Proposal completeness score < 40 (vague proposal)
• High complexity detected (mentions "migration", "breaking change", "refactor")

Deep Analysis using Task Agent:

Spawn Task agent with subagent_type=Explore

Prompt for agent:
"Analyze codebase architecture and patterns for implementing [feature title].

Context:
- Proposal: [brief summary of goals and requirements]
- Keywords: [keywords list]
- Initial findings: [Phase 1 results summary]

Focus on:
1. Overall architecture style (MVC, Clean, Microservices, etc)
2. Existing similar features or modules
3. Code organization conventions
4. Testing patterns
5. Files/modules that would be affected by [feature]

Provide comprehensive understanding of how [feature] would fit into current codebase."

Thoroughness level: "medium"

Phase 2 Duration: 1-2 minutes (if needed)

Output Format

interface CodebaseContext {
  // Similar existing features
  similarFeatures: Array<{
    path: string;
    purpose: string;  // What this file/feature does
    relevance: "high" | "medium" | "low";
  }>;

  // Technology stack
  techStack: {
    languages: string[];  // ["TypeScript", "JavaScript"]
    frameworks: string[];  // ["Laravel 12.2", "Vue 3.4"]
    libraries: string[];  // ["axios", "lodash", "moment"]
    database?: string;  // "PostgreSQL", "MySQL", "MongoDB"
    testing?: string;  // "Jest", "PHPUnit", "pytest"
  };

  // Architecture & patterns
  patterns: {
    architecture: string;  // "MVC", "Clean Architecture", "Layered"
    structure: string;  // "Monorepo", "Monolith", "Modular"
    serviceLayer: boolean;  // Uses service layer pattern?
    repository: boolean;  // Uses repository pattern?
    testingStrategy: string;  // "Unit + Integration", "E2E", "TDD"
    conventions: string[];  // ["TypeScript strict mode", "ESLint", "PSR-12"]
  };

  // Files that might need changes
  potentialConflicts: Array<{
    path: string;
    reason: string;  // Why this file might conflict/need changes
  }>;

  // Integration points
  integrationPoints: Array<{
    type: string;  // "auth", "database", "queue", "email"
    location: string;  // File path or description
    details: string;  // How to integrate
  }>;

  // Analysis metadata
  confidence: "High" | "Medium" | "Low";
  searchPhase: "Targeted" | "Deep";  // Which phase provided this data
  analysisTime: number;  // Seconds taken
}

Example Output

Scenario: Laravel app, notification feature proposal

Input:

{
  parsedProposal: {
    title: "Real-time User Notifications",
    keywords: ["notification", "user", "email", "real-time", "laravel", "database", "queue"]
  },
  workingDirectory: "/home/user/my-laravel-app"
}

Phase 1 Search Results:

Tech Stack Detection:
- Found: composer.json → Laravel 12.2, PHP 8.3
- Found: package.json → Vue 3.4, Vite

Similar Features:
- app/Notifications/WelcomeEmail.php (high relevance)
- app/Services/EmailService.php (medium relevance)
- app/Models/User.php (high relevance)
- config/mail.php (medium relevance)
- config/queue.php (high relevance)

Architecture:
- Found: app/Models/ → MVC pattern
- Found: app/Services/ → Service layer
- Found: tests/Feature/ → Feature tests with Pest

Integration Points:
- User model: app/Models/User.php
- Mail config: config/mail.php (SMTP via Mailgun)
- Queue: config/queue.php (Redis driver)

Output:

{
  "similarFeatures": [
    {
      "path": "app/Notifications/WelcomeEmail.php",
      "purpose": "Existing notification example - sends welcome email to new users",
      "relevance": "high"
    },
    {
      "path": "app/Services/EmailService.php",
      "purpose": "Email sending service - handles SMTP delivery",
      "relevance": "medium"
    },
    {
      "path": "app/Models/User.php",
      "purpose": "User model - target for notifications",
      "relevance": "high"
    }
  ],

  "techStack": {
    "languages": ["PHP 8.3", "JavaScript"],
    "frameworks": ["Laravel 12.2", "Vue 3.4"],
    "libraries": ["Mailgun", "Redis", "Vite"],
    "database": "MySQL",
    "testing": "Pest (PHPUnit)"
  },

  "patterns": {
    "architecture": "MVC with Service Layer",
    "structure": "Monolith",
    "serviceLayer": true,
    "repository": false,
    "testingStrategy": "Feature tests + Unit tests",
    "conventions": [
      "Laravel coding standards",
      "Service layer for business logic",
      "Pest for testing",
      "Vue 3 Composition API for frontend"
    ]
  },

  "potentialConflicts": [
    {
      "path": "app/Models/User.php",
      "reason": "May need Notifiable trait (likely already has it)"
    },
    {
      "path": "config/queue.php",
      "reason": "Queue configuration for async notification delivery"
    }
  ],

  "integrationPoints": [
    {
      "type": "auth",
      "location": "app/Models/User.php",
      "details": "User model should use Notifiable trait for Laravel notifications"
    },
    {
      "type": "queue",
      "location": "config/queue.php",
      "details": "Redis queue configured and ready for async jobs"
    },
    {
      "type": "email",
      "location": "config/mail.php",
      "details": "Mailgun SMTP configured for email delivery"
    }
  ],

  "confidence": "High",
  "searchPhase": "Targeted",
  "analysisTime": 45
}

Usage in Judgement Flow

Judges receive this context to make informed decisions:

Pragmatist uses:

• similarFeatures → Can we reuse existing code?
• integrationPoints → Integration effort estimate
• techStack.testing → Is testing setup ready?

Purist uses:

• patterns.architecture → Does proposal fit current architecture?
• patterns.conventions → Will this follow existing conventions?
• serviceLayer/repository → Proper separation of concerns?

Innovator uses:

• techStack.libraries → Are we using latest/best libraries?
• patterns → Opportunity to improve architecture?

Skeptic uses:

• potentialConflicts → What could break?
• integrationPoints → Security implications of integrations?

Optimizer uses:

• techStack.database → Database optimization opportunities?
• similarFeatures → Performance patterns to follow/avoid?

Edge Cases

Empty/New Project:

{
  "similarFeatures": [],
  "techStack": {
    "languages": [],
    "frameworks": [],
    "libraries": []
  },
  "patterns": {
    "architecture": "Unknown",
    "structure": "Unknown",
    "serviceLayer": false,
    "repository": false,
    "testingStrategy": "None detected",
    "conventions": []
  },
  "potentialConflicts": [],
  "integrationPoints": [],
  "confidence": "Low",
  "searchPhase": "Targeted",
  "analysisTime": 15
}

Judges should note: "New/empty codebase - no existing patterns to follow"

Large Monorepo (1000+ files):

• Limit search depth to relevant packages/apps
• Use glob patterns to narrow scope
• May need Phase 2 deep analysis
• Increase timeout for searches

Multiple Frameworks Detected:

{
  "techStack": {
    "frameworks": ["Laravel 12.2 (backend)", "Next.js 14 (frontend)", "React Native (mobile)"]
  }
}

Judges should consider: Which part of the stack does feature target?

Performance Optimization

Caching:

• Cache tech stack detection (rarely changes)
• Cache file structure for 5 minutes
• Don't re-scan if same proposal keywords

Timeouts:

• Phase 1: 60 second timeout
• Phase 2: 120 second timeout
• If timeout: return partial results with confidence: "Low"

Parallel Searches:

• Run Glob and Grep in parallel when possible
• Tech stack detection parallel to feature search

Error Handling

No package/config files found:

• Continue with generic analysis
• Set confidence: "Low"
• Recommend manual tech stack specification

Grep/Glob errors:

• Log error but continue
• Try alternative search patterns
• Fallback to Phase 2 if available

Permission denied errors:

• Skip inaccessible directories
• Note in output: "Some directories inaccessible"
• Reduce confidence accordingly

Phase 2 agent fails:

• Fall back to Phase 1 results
• Set confidence: "Medium" (downgrade from High)
• Note: "Deep analysis unavailable"

Success Criteria

Excellent Analysis (confidence: High):

• Found 5+ similar features
• Tech stack fully identified
• Architecture pattern clear
• Integration points identified

Good Analysis (confidence: Medium):

• Found 2-4 similar features
• Tech stack partially identified
• Some architecture clues
• Basic integration points

Poor Analysis (confidence: Low):

• Found 0-1 similar features
• Tech stack unknown
• Architecture unclear
• No integration points

Judges will weight their feedback based on confidence level.