Refactor Review

Purpose

Find code that should be simpler. LLM-generated codebases develop a specific pathology: each prompt produces reasonable code in isolation, but the accumulated result has duplicated utilities, inconsistent patterns, over-abstracted layers, and truncated blocks where a previous generation was cut short. This skill identifies concrete refactoring opportunities and flags drift from the project's stated architecture.

Inputs

• The full codebase
• project-context.md — stated architecture, patterns, and constraints
• features.md — what features exist and their status

Outputs

See references/review-lens-framework.md for the shared output pattern. Lens name for DB operations: refactor-review

Instructions

Fresh Findings Check

See references/review-lens-framework.md. Lens: refactor-review.

1. Load Context

Read project-context.md and features.md. Understand:

• What patterns and conventions does the project claim to follow?
• What's the intended module structure?
• What scale is this built for? (Over-engineering for a small tool is different than under-engineering for a platform.)

2. Duplication Scan

Find code that's repeated instead of shared:

• Near-identical functions in different files (same logic, different names)
• Copy-pasted blocks with minor variations (should be parameterized)
• Multiple implementations of the same utility (string formatting, date parsing, error handling)
• Repeated boilerplate that should be abstracted (API call patterns, DB queries)

For each instance, estimate the deduplication savings (lines removed, files simplified).

3. Over-Engineering Detection

Flag unnecessary complexity:

• Abstractions with only one implementation (interfaces/abstract classes used once)
• Factory patterns for creating a single type
• Plugin systems with no plugins
• Config systems more complex than the features they configure
• Generic frameworks built for a specific use case
• Multiple layers of indirection that add no value (wrapper functions that just forward args)
• Event systems or pub/sub patterns used for simple direct calls

The test: if removing the abstraction and inlining the code makes it easier to understand with no loss of functionality, it's over-engineered.

4. Truncation and Incomplete Code

LLM-specific pattern: code that was generated in a previous session but truncated mid-function, then a new session continued without completing the original. Look for:

• Functions that start complex logic but return early with a simplified path
• Comment blocks like // ... rest of implementation or // TODO: complete this
• Error handlers that catch but don't handle (empty catch blocks)
• Switch/match statements missing obvious cases
• Functions whose name promises more than the body delivers

5. Consistency Audit

Check for pattern inconsistency across the codebase:

• Mixed async patterns (callbacks + promises + async/await in the same project)
• Inconsistent error handling (some functions throw, some return null, some return Result)
• Mixed naming conventions (camelCase and snake_case in the same language)
• Inconsistent file organization (some features in one file, others split across many)
• Multiple ways of doing the same thing (fetch + axios, moment + dayjs)

6. Drift Check

Compare the code's actual structure against project-context.md:

• Does the module structure match what's documented?
• Are the stated patterns actually followed consistently?
• Have new patterns emerged in the code that aren't documented?
• Are there modules or features that don't appear in any project doc?

7. Produce Findings

Format each finding using this structure (store via db_upsert as shown in Outputs above):

## [SEVERITY] Finding Title

**Category**: Duplication | Over-Engineering | Truncation | Inconsistency | Drift
**Location**: file/path:line (list all affected files for duplication findings)
**Impact**: Lines of code affected, complexity reduction potential

**Problem**: What's wrong, specifically.

**Evidence**: Code snippets showing the issue. For duplication, show both copies side by side.

**Recommendation**: Specific refactoring steps. Name the target function/module/pattern.
Include a brief sketch of the simplified version where helpful.

Severity levels:

• CRITICAL — Truncated/incomplete code that will fail at runtime
• HIGH — Significant duplication or over-engineering that impedes maintainability
• MEDIUM — Inconsistency or mild over-engineering that causes confusion
• LOW — Style or organization improvement

8. Summarize

End with:

• Count of findings by severity and category
• Estimated total lines of code that could be removed through deduplication
• Top 3 highest-impact refactors (the ones that would simplify the most code)
• Overall assessment: is this codebase clean, or does it need a cleanup pass?

Execution Mode

See references/review-lens-framework.md. Lens: refactor-review.

Examples

User: This codebase feels bloated. Find what can be simplified.
→ Triggers refactor-review. Full scan with emphasis on duplication and over-engineering.

User: We've been building for 3 weeks with AI. Is there accumulated cruft?
→ Triggers refactor-review. Emphasis on truncation detection and consistency audit,
  since multi-session AI work accumulates these specific problems.

User: Before I refactor the API layer, tell me what else needs cleanup too.
→ Triggers refactor-review. Produce a prioritized list so the user can batch refactors.

---

Before completing, read and follow ../references/review-lens-framework.md and ../references/cross-cutting-rules.md.