name: codebase-analysis
description: Deep dive analysis of any codebase. Maps architecture, identifies patterns, finds issues, and generates comprehensive reports. Use before major refactoring or when onboarding to unfamiliar code.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Codebase Analysis

Systematic deep-dive into any codebase to understand architecture, patterns, and issues.

Analysis Framework

1. SURVEY      → High-level structure scan
2. TRACE       → Follow key flows through code
3. IDENTIFY    → Find patterns and anti-patterns
4. MEASURE     → Quantify code quality metrics
5. REPORT      → Generate actionable findings

Phase 1: Survey

Structure Scan

Analyze:
- Root files (config, entry points)
- Folder organization
- Key directories
- Dependency graph

Questions to Answer

□ What's the entry point?
□ How is code organized?
□ What are the main modules/features?
□ What external dependencies?
□ What build/deploy configuration?

Phase 2: Trace Key Flows

Pick 3-5 critical user flows and trace them:

Flow Tracing Template

## Flow: User Login

### Entry Point
- File: src/features/auth/LoginScreen.tsx
- Trigger: User clicks "Sign In"

### Data Flow
1. UI captures credentials
2. → AuthService.login()
3. → Supabase client call
4. → Token stored in state
5. → Redirect to dashboard

### Components Touched
- LoginScreen (UI)
- AuthService (logic)
- useAuth hook (state)
- supabaseClient (external)

### Observations
- Good: Separation of concerns
- Issue: No error handling on line 45
- Issue: Hardcoded redirect path

Phase 3: Pattern Identification

Positive Patterns to Note

✓ Repository pattern
✓ Dependency injection
✓ Consistent naming
✓ Type safety
✓ Error boundaries
✓ Loading states
✓ Test coverage

Anti-Patterns to Flag

✗ God components (>300 lines)
✗ Prop drilling (>3 levels)
✗ Direct API calls in UI
✗ Inconsistent state management
✗ Missing error handling
✗ Hardcoded values
✗ Dead code
✗ Circular dependencies
✗ Mixed responsibilities

Pattern Detection Queries

# Find large files (potential god objects)
find . -name "*.ts" -o -name "*.dart" | xargs wc -l | sort -n | tail -20

# Find TODO/FIXME comments
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.dart"

# Find console.log (should be cleaned)
grep -r "console.log\|print(" --include="*.ts" --include="*.dart"

# Find hardcoded strings
grep -r "http://\|https://" --include="*.ts" --include="*.dart"

Phase 4: Metrics

Code Quality Metrics

Generate Metrics Report

## Code Metrics

### File Size Distribution
- Small (<100 lines): 45 files
- Medium (100-300 lines): 23 files
- Large (>300 lines): 7 files ⚠️

### Largest Files (Need Review)
1. UserDashboard.tsx (523 lines) ❌
2. ApiClient.ts (412 lines) ⚠️
3. utils.ts (389 lines) ⚠️

### Dependency Health
- Total: 47 packages
- Outdated: 12 ⚠️
- Vulnerable: 2 ❌

Phase 5: Report Generation

Analysis Report Template

# Codebase Analysis Report
**Project**: [name]
**Date**: [date]
**Analyst**: Claude + Human

## Executive Summary
[2-3 sentence overview]

## Architecture Overview
[Diagram or description]

## Strengths
1. [Positive finding]
2. [Positive finding]
3. [Positive finding]

## Critical Issues (Fix Immediately)
1. **[Issue]**: [location] - [impact]
2. **[Issue]**: [location] - [impact]

## Improvement Opportunities
1. [Improvement] - Priority: High/Medium/Low
2. [Improvement] - Priority: High/Medium/Low

## Technical Debt Inventory
| Item | Location | Effort | Impact |
|------|----------|--------|--------|
| [debt] | [file] | [hours] | [risk] |

## Recommendations
### Quick Wins (< 1 day)
- [action]

### Short Term (1 week)
- [action]

### Long Term (1 month+)
- [action]

## Next Steps
1. Review this report with team
2. Prioritize issues
3. Run /architecture-cleanup for fixes

Integration with Other Skills

After analysis:
- Use /architecture-cleanup to fix issues
- Use /sprint-planning to plan improvements
- Use framework-specific skills for implementation

Output Artifacts

This skill produces:
- ANALYSIS_REPORT.md - Full findings
- ARCHITECTURE.md - Architecture documentation
- TECH_DEBT.md - Technical debt inventory
- List of files needing attention