codebase-analysis

name	codebase-analysis
description	Techniques for analyzing existing codebases to reverse-engineer requirements and understand business logic. Use when conducting brownfield analysis or understanding existing system capabilities.
allowed-tools	Read, Grep, Glob, LSP

Codebase Analysis Skill

Overview

This skill provides techniques for extracting business requirements, domain knowledge, and technical specifications from existing codebases.

Analysis Objectives

When analyzing a codebase, seek to understand:

1. Domain Model: Core entities and their relationships
2. Business Rules: Validation, calculations, workflows
3. Integrations: External systems and data flows
4. User Capabilities: What users can do in the system
5. Technical Constraints: Architecture patterns and limitations

Analysis Process

Phase 1: Structure Discovery

1. Map project structure and organization
2. Identify main components and layers
3. Locate configuration and entry points
4. Understand build and deployment setup

Phase 2: Domain Model Extraction

1. Find entity/model definitions
2. Map relationships between entities
3. Identify domain vocabulary (ubiquitous language)
4. Document data types and constraints

Phase 3: Business Logic Identification

1. Locate service/business logic layers
2. Extract validation rules
3. Document calculations and formulas
4. Map state machines and workflows

Phase 4: Integration Mapping

1. Find API endpoints and contracts
2. Identify external service calls
3. Map data flows in/out of system
4. Document authentication patterns

Phase 5: Capability Documentation

1. List user-facing features
2. Map permissions and access control
3. Document user workflows
4. Identify edge cases and error handling

Code Pattern Recognition

Entity/Model Identification

Look for these patterns:

// C# Entity
public class Order { ... }

// Java Entity
@Entity
public class Order { ... }

// TypeScript Interface
interface Order { ... }

// Database Schema
CREATE TABLE orders ( ... )

Business Rule Indicators

Watch for these keywords and patterns:

• Validation: Validate, Check, Ensure, Must, Should
• Calculations: Calculate, Compute, Total, Sum
• Conditions: If, When, Unless, Only
• Constraints: Max, Min, Required, Limit

Service Layer Patterns

Identify business logic in:

// Service classes
public class OrderService { ... }

// Use cases / Application services
public class CreateOrderUseCase { ... }

// Command/Query handlers
public class CreateOrderHandler { ... }

API Endpoint Patterns

Look for:

// REST Controllers
[Route("api/orders")]
[HttpPost]
public async Task<Order> Create(...)

// Express routes
app.post('/api/orders', ...)

// GraphQL resolvers
Mutation: { createOrder: ... }

Analysis Heuristics

Finding Domain Models

1. Search for class, interface, type definitions
2. Look in folders named: Models, Entities, Domain
3. Check database migrations and schema files
4. Review ORM configurations

Finding Business Rules

1. Search for validation attributes/decorators
2. Look for throw statements (business exceptions)
3. Find conditional logic in services
4. Check for rule engines or policy patterns

Finding Integrations

1. Search for HTTP client usage
2. Look for message queue producers/consumers
3. Find database connection configurations
4. Check for external SDK imports

Finding User Capabilities

1. Review API endpoints and their permissions
2. Check UI components and forms
3. Look at authorization/role definitions
4. Review menu structures and navigation

Output Artifacts

Domain Model Documentation

## Entity: Order

### Attributes
| Name | Type | Description | Constraints |
|------|------|-------------|-------------|
| id | UUID | Unique identifier | Required |
| status | Enum | Order status | Required |
| total | Decimal | Order total | >= 0 |

### Relationships
- Order has many OrderItems (1:N)
- Order belongs to Customer (N:1)

### Business Rules
- Order total must equal sum of item totals
- Status can only transition: Draft -> Submitted -> Approved -> Completed

Business Rule Documentation

## Rule: Order Validation

### Description
Orders must meet these criteria before submission

### Conditions
1. Order must have at least one item
2. All items must have valid product references
3. Customer must have valid payment method
4. Total must be greater than $0

### Implementation
- File: src/Services/OrderService.cs
- Method: ValidateForSubmission()
- Line: 145-180

Integration Documentation

## Integration: Payment Gateway

### Type
REST API (Synchronous)

### Endpoint
POST https://api.payments.com/v1/charges

### Data Flow
- Input: Order total, Customer payment token
- Output: Transaction ID, Status

### Error Handling
- Timeout: Retry 3 times with exponential backoff
- Failure: Mark order as payment pending, notify support

### Implementation
- File: src/Integrations/PaymentGateway.cs

Code Search Patterns

Finding Entities (by language)

# C# / .NET
grep -r "public class.*Entity" --include="*.cs"
grep -r "\[Table\(" --include="*.cs"

# Java
grep -r "@Entity" --include="*.java"

# TypeScript
grep -r "interface.*{" --include="*.ts"

Finding Validation Rules

# C# Attributes
grep -r "\[Required\]|\[Range\]|\[StringLength\]" --include="*.cs"

# Java Annotations
grep -r "@NotNull|@Size|@Valid" --include="*.java"

# Custom validation
grep -r "Validate|throw.*Exception" --include="*.cs"

Finding API Endpoints

# .NET Controllers
grep -r "\[Http.*\]|\[Route\(" --include="*.cs"

# Express.js
grep -r "app\.(get|post|put|delete)\(" --include="*.js"

Reverse Engineering Tips

Start With Entry Points

1. Find main() or startup configuration
2. Follow dependency injection setup
3. Trace from API controllers to services to data

Follow the Data

1. Start with database schema or entities
2. Trace how data flows through system
3. Map CRUD operations for each entity

Look for Tests

1. Unit tests reveal expected behavior
2. Integration tests show workflows
3. Test data shows valid/invalid scenarios

Check Documentation

1. Look for README files
2. Check API documentation (Swagger/OpenAPI)
3. Review code comments and XML docs

Questions to Answer

After analysis, you should be able to answer:

1. What entities exist and how do they relate?
2. What can users do in this system?
3. What business rules govern behavior?
4. What external systems does this integrate with?
5. What are the key workflows?
6. What constraints exist (technical and business)?
7. What data does the system manage?
8. Who has access to what?

See patterns.md for common architectural patterns to identify.