Codebase Improvement Planner

Session: ${CLAUDE_SESSION_ID} Task List: ${CLAUDE_CODE_TASK_LIST_ID}

Purpose

Comprehensive codebase analysis and improvement planning with actionable recommendations.

Phase 1: Discovery & Analysis

1.1 Project Structure Mapping

# Get project overview
echo "=== PROJECT STRUCTURE ==="
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) | head -100

# Count files by type
echo "=== FILE COUNTS ==="
for ext in ts tsx js jsx py go rs java; do
  count=$(find . -type f -name "*.$ext" 2>/dev/null | wc -l)
  [ "$count" -gt 0 ] && echo "$ext: $count files"
done

# Check for configuration files
echo "=== CONFIG FILES ==="
ls -la package.json pyproject.toml Cargo.toml go.mod pom.xml 2>/dev/null || echo "No standard config found"

1.2 Dependency Analysis

# Node.js dependencies
[ -f package.json ] && echo "=== NPM DEPENDENCIES ===" && cat package.json | grep -A 100 '"dependencies"' | head -50

# Python dependencies
[ -f requirements.txt ] && echo "=== PIP REQUIREMENTS ===" && cat requirements.txt
[ -f pyproject.toml ] && echo "=== PYPROJECT ===" && cat pyproject.toml

# Outdated checks
[ -f package.json ] && npm outdated 2>/dev/null || true

1.3 Code Quality Indicators

# TODO/FIXME/HACK comments
echo "=== TECHNICAL DEBT MARKERS ==="
grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|DEPRECATED" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -50

# Large files (potential refactoring candidates)
echo "=== LARGE FILES (>500 lines) ==="
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" \) -exec wc -l {} \; 2>/dev/null | awk '$1 > 500 {print}' | sort -rn | head -20

# Complex functions (high cyclomatic complexity indicators)
echo "=== POTENTIAL COMPLEXITY ISSUES ==="
grep -rn "if.*if.*if\|&&.*&&.*&&\|||.*||.*||" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | head -20

Phase 2: Parallel Deep Analysis

Launch specialized analysis agents:

Agent 1: Security Scanner

Analyze for:
- Hardcoded secrets/credentials
- SQL injection vulnerabilities
- XSS vulnerabilities
- Insecure dependencies
- Missing input validation
- Exposed sensitive data in logs

Agent 2: Performance Analyzer

Identify:
- N+1 query patterns
- Synchronous blocking operations
- Memory leak indicators
- Inefficient algorithms (O(n²) or worse)
- Missing caching opportunities
- Large bundle sizes

Agent 3: Test Coverage Auditor

Assess:
- Test file coverage
- Missing test scenarios
- Test quality (assertions per test)
- Integration vs unit test ratio
- Mock usage patterns

Agent 4: Architecture Reviewer

Evaluate:
- SOLID principle adherence
- Separation of concerns
- Dependency injection usage
- Module coupling/cohesion
- API design consistency
- Error handling patterns

Agent 5: Documentation Checker

Review:
- README completeness
- API documentation
- Code comments quality
- Changelog maintenance
- Architecture decision records

Phase 3: Issue Classification

Priority Matrix

Issue Template

issue:
  id: "IMP-001"
  title: ""
  priority: "P0|P1|P2|P3"
  category: "security|performance|quality|testing|architecture|documentation"
  location:
    file: ""
    line_start: 0
    line_end: 0
  description: ""
  impact: ""
  recommendation: ""
  effort_estimate: "S|M|L|XL"
  dependencies: []

Phase 4: Improvement Roadmap Generation

Roadmap Structure

improvement_roadmap:
  sprint_1_critical:
    duration: "1-2 weeks"
    focus: "Security & Stability"
    tasks:
      - id: "IMP-001"
        title: ""
        assignee_type: "senior_developer"
        
  sprint_2_foundation:
    duration: "2-3 weeks"
    focus: "Testing & Architecture"
    tasks: []
    
  sprint_3_optimization:
    duration: "2-3 weeks"
    focus: "Performance & Quality"
    tasks: []
    
  sprint_4_polish:
    duration: "1-2 weeks"
    focus: "Documentation & Cleanup"
    tasks: []

Phase 5: Execution Guidelines

For Each Improvement Task:

1. Preparation

   • Create feature branch: improvement/IMP-XXX-description
   • Review related code
   • Identify test requirements

2. Implementation

   • Follow TDD approach
   • Make atomic commits
   • Document changes

3. Validation

   • Run full test suite
   • Performance benchmarks (if applicable)
   • Security scan (if applicable)

4. Review

   • Self-review with code-reviewer agent
   • Update documentation
   • Create PR with detailed description

5. Merge

   • Squash commits if needed
   • Update CHANGELOG
   • Close related issues

Output Format

Generate report as:

.claude/reports/
├── improvement-analysis-${CLAUDE_SESSION_ID}.md
├── security-findings-${CLAUDE_SESSION_ID}.json
├── performance-recommendations-${CLAUDE_SESSION_ID}.json
└── roadmap-${CLAUDE_SESSION_ID}.yaml

Invocation

To use this skill:

1. Navigate to project root
2. Run: Analyze this codebase and create an improvement plan
3. Review generated reports in .claude/reports/
4. Execute improvements using task list: CLAUDE_CODE_TASK_LIST_ID=improvement-${PROJECT_NAME}