# Review Codebase

> Analyze codebase for optimization and refactoring opportunities. Use for periodic quality checks, identifying tech debt, and planning improvements.

- Skill: `l3wi/review-codebase` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add l3wi/review-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/review-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/review-codebase

---


# Codebase Review Skill

Perform comprehensive codebase analysis to identify optimization opportunities, technical debt, and refactoring needs.

## Usage

```
/skill:review-codebase                     # Full codebase review
/skill:review-codebase src/components      # Review specific directory
/skill:review-codebase --focus security    # Focus on security issues
/skill:review-codebase --focus performance # Focus on performance issues
```

## Focus Areas

Available focus modes:
- `security` - Security vulnerabilities and hardening opportunities
- `performance` - Performance bottlenecks and optimization opportunities
- `quality` - Code quality, complexity, and maintainability
- `testing` - Test coverage gaps and testing improvements
- `docs` - Documentation completeness and accuracy

## Workflow

### 1. Scope Definition

If no scope provided, analyze full codebase:
```
src/          # Application code
lib/          # Shared libraries
components/   # UI components
```

Exclude by default:
- `node_modules/`
- `dist/`, `build/`, `.next/`
- `.git/`
- Test files (unless focus is testing)

### 2. Code Analysis

Analyze the codebase for:

**Complexity:**
- Cyclomatic complexity
- Cognitive complexity
- File length, function length

**Duplication:**
- Similar code patterns
- Copy-paste code

**Dependencies:**
- Outdated packages
- Deprecated APIs
- Security vulnerabilities

**Patterns:**
- Anti-patterns
- Code smells
- Inconsistent conventions

### 3. Documentation Audit

Check documentation health:
- README accuracy (commands match package.json)
- API documentation coverage
- Spec implementation status
- PRD→Spec→Code traceability
- ADR validity (superseded links, stale proposals)
- Environment variable documentation

### 4. Compile Report

Create comprehensive review document:

1. Read template from `docs/reviews/_template.md`
2. Populate with findings
3. Calculate health scores
4. Prioritize recommendations
5. Write to `docs/reviews/{date}-review.md`

### 5. Generate Tasks

For actionable items, create task files:

```
docs/tasks/refactor-{component}.md
docs/tasks/fix-{issue}.md
docs/tasks/upgrade-{dependency}.md
```

Priority based on:
- Impact (how much improvement)
- Effort (how hard to fix)
- Risk (consequences of not fixing)

### 6. Present Summary

Output summary with:
- Overall health score
- Top 3-5 critical issues
- Quick wins (high impact, low effort)
- Link to full report

### 7. Suggest Next Steps

Based on findings, recommend appropriate actions:

| Finding Type | Recommended Action |
|--------------|-------------------|
| Quick fixes (< 1 hour) | Implement directly or plan mode |
| Medium improvements | Plan mode with `docs/tasks/` |
| Major refactoring | `/skill:plan {feature} --spec --from-review {review-file}` |
| New capability needed | `/skill:plan {feature}` |

**For significant improvements:**
```
This review identified major improvements for {area}.
Consider running: /skill:plan {area-name} --spec --from-review docs/reviews/{date}-review.md
```

## Output

- **Primary**: `docs/reviews/{date}-review.md`
- **Secondary**: `docs/tasks/*.md` (generated tasks)
- **Suggested**: Next steps based on severity

## Analysis Metrics

### Complexity Thresholds

| Metric | Good | Warning | Critical |
|--------|------|---------|----------|
| Cyclomatic Complexity | <10 | 10-20 | >20 |
| Cognitive Complexity | <15 | 15-30 | >30 |
| File Length | <300 | 300-500 | >500 |
| Function Length | <50 | 50-100 | >100 |

### Code Health Scoring

Each category scored 1-5:
- **5**: Excellent - exceeds best practices
- **4**: Good - meets best practices
- **3**: Acceptable - minor improvements needed
- **2**: Concerning - significant improvements needed
- **1**: Critical - immediate attention required

Overall health = average of category scores

## Refactoring Patterns

Apply these patterns when improvements are needed:

### Extract Function
- Functions > 50 lines
- Multiple levels of abstraction
- Code with comments explaining sections

### Replace Nested Conditionals with Guard Clauses
- Deep nesting (> 3 levels)
- Multiple validation checks
- Happy path buried in else clauses

### Introduce Parameter Object
- Functions with > 3 parameters
- Related parameters always passed together

### Decompose Conditional
- Complex boolean expressions
- Business logic embedded in conditions

### Strangler Fig (Incremental Replacement)
- Replacing legacy systems
- Migrating to new architecture

### Move Function to Appropriate Module
- Function uses more from another module
- Cross-module dependencies are circular

## Anti-Patterns to Flag

- **Premature Abstraction** - Helpers for one-time operations
- **Over-Engineering** - Flexibility not needed (YAGNI)
- **Shotgun Surgery** - One change requires many file modifications
- **Feature Envy** - Functions using another class's data excessively
- **God Objects** - Classes doing too much

## Example

```
User: /skill:review-codebase src/components --focus quality

Pi: Starting codebase review of src/components...

[Analyzing code...]
[Checking documentation...]

Review complete.

## Summary

**Overall Health**: 3.4 / 5 (Acceptable)

| Category | Score |
|----------|-------|
| Code Quality | 3 |
| Test Coverage | 4 |
| Documentation | 3 |
| Architecture | 4 |
| Security | 3 |

## Critical Issues

1. **High complexity in UserDashboard.tsx** (cyclomatic: 32)
   - Extract sub-components for widget rendering
   - Pattern: Extract Function

2. **Outdated react-query** (v3 -> v5)
   - Breaking changes require migration
   - Security advisory in v3

## Quick Wins

1. Remove 12 unused imports across 8 files
2. Add missing error boundaries to 3 components
3. Enable strict TypeScript in 2 config files

Full report: docs/reviews/2024-01-15-review.md
Generated tasks: 7 task files in docs/tasks/

## Suggested Next Steps

For the high-complexity UserDashboard, consider:
/skill:plan dashboard-refactor --spec --from-review docs/reviews/2024-01-15-review.md
```

## Related

- `/skill:feature` - Implement improvements
- `/skill:plan` - Planning workflow (PRD → Spec → Tasks)