Code Inspection Guide

Overview

This skill performs a comprehensive code quality analysis to identify refactoring opportunities and code smells. The analysis is read-only and produces a detailed refactoring recommendation plan without making any changes to the codebase.

Scope

By default, analyze the entire project. Users can specify specific files or directories to inspect if needed.

Output

Generate a refactoring recommendation plan and write it to @docs/refactoring-recommendations.md in the current project directory.

Analysis Areas

1. Code Duplication

Identify opportunities to eliminate duplicate code:

• Similar or identical code blocks across multiple files
• Repeated logic that could be extracted into shared functions/methods
• Copy-pasted code with minor variations
• Duplicated constants or configuration values
• Similar class structures that could use inheritance or composition

2. Data Flow Issues

Identify confusing or problematic data patterns:

• Unclear data transformations (input -> output not obvious)
• Excessive mutations of shared state
• Complex data pipelines that are hard to follow
• Inconsistent data validation or sanitization
• Data flowing through too many layers unnecessarily
• Mixed responsibilities in data transformation functions
• Hidden side effects in data operations

3. Architectural Smells

Identify design and structure issues:

• Tight coupling between modules/classes
• Missing abstraction layers
• God objects (classes doing too much)
• Feature envy (methods using more data from other classes)
• Inappropriate intimacy (classes too dependent on each other's internals)
• Circular dependencies
• Violation of separation of concerns
• Missing or unclear boundaries between layers
• Inconsistent error handling patterns

4. Code Smells

Identify general code quality issues:

• Long methods/functions (>50 lines)
• Complex conditionals (deeply nested if/else)
• High cyclomatic complexity
• Unclear or misleading variable/function names
• Magic numbers or hardcoded values
• Dead code or unused imports
• Inconsistent naming conventions
• Overly complex class hierarchies
• Methods with too many parameters (>4)
• Switch/case statements that should be polymorphism
• Comments explaining "what" instead of "why"
• Lack of error handling or over-broad exception catching

Inspection Process

Step 1: Understand the Project

• Identify the project structure and main directories
• Understand the primary programming language(s)
• Note the project type (web app, library, CLI tool, etc.)
• Review any existing documentation or architecture notes

Step 2: Scan and Analyze

Systematically review the codebase focusing on:

• Core business logic files
• Frequently modified files (check git history if available)
• Large files (likely to have complexity issues)
• Files with many dependencies

For each file analyzed, look for the issues described in the Analysis Areas section.

Step 3: Prioritize Findings

Categorize issues by severity:

• Critical: Major architectural problems, security issues, or severe code duplication
• High: Significant code smells affecting maintainability
• Medium: Moderate refactoring opportunities
• Low: Minor improvements and style consistency

Step 4: Generate Recommendations

For each finding, provide:

• Location: Exact file path and line numbers (e.g., src/utils/helper.ts:45-67)
• Issue Type: Which category (duplication, data flow, architectural, code smell)
• Severity: Critical, High, Medium, or Low
• Description: Clear explanation of the problem
• Current Code Pattern: Brief description or snippet of the problematic pattern
• Recommended Refactoring: Specific, actionable steps to improve the code
• Benefits: What will improve (maintainability, testability, readability, etc.)

Report Format

Structure the output document as follows:

# Code Inspection Report
Generated: [Date]

## Executive Summary
- Total files analyzed: [number]
- Total issues found: [number]
- Critical: [number], High: [number], Medium: [number], Low: [number]

## Key Findings
[Brief overview of the most important issues]

## Detailed Recommendations

### Critical Priority

#### [Issue Title]
- **Location**: `path/to/file.ext:line-range`
- **Type**: [Code Duplication | Data Flow | Architectural | Code Smell]
- **Description**: [What's wrong]
- **Current Pattern**: [How it works now]
- **Recommended Refactoring**: [What to do]
- **Benefits**: [Why this helps]

[Repeat for each critical issue]

### High Priority
[Same format as Critical]

### Medium Priority
[Same format as Critical]

### Low Priority
[Same format as Critical]

## Refactoring Strategy
[Suggested order of operations for implementing the recommendations]

## Next Steps
[Concrete action items for the development team]

Important Notes

• Read-Only: This skill MUST NOT modify any code files
• No Execution: Do not run tests, builds, or any other commands that modify state
• Document Only: All output goes to the refactoring recommendations document
• Be Specific: Always include exact file paths and line numbers
• Be Actionable: Each recommendation should have clear steps
• Be Realistic: Consider the effort vs. benefit trade-off
• Respect Existing Patterns: Note when the team has intentionally chosen certain patterns

Completion Criteria

• All relevant code files have been analyzed
• Findings are categorized and prioritized
• Each issue has specific location references
• Recommendations are clear and actionable
• Report is written to @docs/refactoring-recommendations.md
• User is notified that the inspection is complete