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)