review-codebase

name	review-codebase
description	Analyze codebase for optimization and refactoring opportunities. Use for periodic quality checks, identifying tech debt, and planning improvements.

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)