Code Simplifier

Code Simplifier

Analyze recently modified code and suggest refinements that improve clarity, consistency, and maintainability - without changing what the code does. The review covers three complementary aspects:

1. Code Reuse - Eliminate duplication, consolidate shared logic, leverage existing utilities. 2. Code Quality - Improve naming, reduce complexity, enforce project standards from AGENTS.md. 3. Efficiency - Fix algorithmic issues, remove unnecessary work, optimize resource usage.

Review Process

Identify the Scope

By default, focus on recently modified code. Use git diff or the file list from the current PR/MR to determine the changed files. When the user specifies a different scope, follow their instruction:

• Specific files: "simplify src/auth.py" - review only the named files
• Directory: "simplify the utils/ folder" - review all files in that directory
• Full repo: "simplify the whole project" - review the entire codebase
• PR/MR: "simplify this PR" - review only files changed in the current PR/MR

Sub-Agent Delegation (Preferred)

When sub-agent capability is available, delegate each review aspect to a separate sub-agent for parallel, focused analysis:

1. Code Reuse Review Agent - Read references/code-reuse-review.md and analyze the changed files for duplication and consolidation opportunities. 2. Code Quality Review Agent - Read references/code-quality-review.md and analyze the changed files for clarity, naming, complexity, and standards compliance. 3. Efficiency Review Agent - Read references/efficiency-review.md and analyze the changed files for performance and resource usage issues.

Each sub-agent should:

• Read the corresponding reference document for detailed criteria and output format
• Read AGENTS.md at the repository root for project-specific coding conventions
• Analyze only the recently changed code (unless instructed otherwise)
• Return findings in the format specified by its reference document

After all sub-agents complete, synthesize their findings into a single consolidated report.

Sequential Review (Fallback)

When sub-agents are not available, perform all three reviews sequentially:

1. Read references/code-reuse-review.md - review for duplication and reuse 2. Read references/code-quality-review.md - review for clarity and standards 3. Read references/efficiency-review.md - review for performance and resources

Apply the criteria and output format from each reference document.

Guiding Philosophy

• Preserve Functionality: Never change what the code does - only how it does it. All original features, outputs, and behaviors remain intact.
• Follow Project Standards: Apply the coding conventions from AGENTS.md at the repository root (import ordering, naming, module structure, error handling, component patterns).
• Clarity Over Brevity: Prefer explicit, readable code over compact one-liners. Avoid nested ternaries - use if/else or switch for multiple conditions.
• Maintain Balance: Avoid over-simplification that reduces clarity, creates overly clever solutions, or combines too many concerns into a single function.
• Pragmatism: Solve real problems, not imaginary ones. Do not optimize for theoretical edge cases or micro-benchmarks that do not matter at the project's scale.

Consolidated Output Format

Present the combined results from all three review aspects:

## Code Simplification Review

### Scope
[List of files reviewed and how scope was determined]

### Code Reuse
[Findings from the reuse review, using **[REUSE]** tags]

### Code Quality
[Findings from the quality review, using **[QUALITY]** tags]

### Efficiency
[Findings from the efficiency review, using **[EFFICIENCY]** tags]

### Summary
[Overall assessment: is the code in good shape, or does it need significant refinement?]
[Prioritized list of the most impactful changes to make first]

When a review aspect has no findings, include it with an explicit "no issues found" statement rather than omitting the section.

Reference Files

• `references/code-reuse-review.md` - Detailed criteria for detecting duplication, consolidation opportunities, and over-abstraction
• `references/code-quality-review.md` - Detailed criteria for naming, complexity, error handling, and project standards compliance
• `references/efficiency-review.md` - Detailed criteria for algorithmic complexity, unnecessary work, resource usage, and I/O patterns

Read and follow the complete instructions in the SKILL.md file located in this skill's directory.

$ARGUMENTS

Code Simplifier

A code simplification skill that analyzes recently modified code and suggests refinements across three dimensions:

How It Works

The skill reviews recently changed code (via git diff or PR file list) and produces a consolidated report with tagged findings ([REUSE], [QUALITY], [EFFICIENCY]).

When sub-agents are available, each aspect is delegated to a separate agent for parallel, focused analysis. Otherwise, the review is performed sequentially.

Adapted From

This skill is adapted from the code-simplifier plugin in the Claude Plugins Official repository. Key adaptations:

• Split into three focused review aspects (reuse, quality, efficiency) instead of a single pass
• References project conventions via AGENTS.md instead of CLAUDE.md
• Supports sub-agent delegation for parallel review
• Uses progressive disclosure with reference documents

Usage

Trigger phrases: "simplify code", "refine code", "clean up code", "improve code quality", or request a simplification review of recent changes.

The skill reads AGENTS.md at the repository root to understand project-specific coding conventions before reviewing.

Code Quality Review

A detailed reference for evaluating code clarity, consistency, and maintainability in recently modified code. Focus on structural simplicity, naming, readability, and adherence to project standards - while preserving all existing functionality.

Core Principles

1. Clarity Over Brevity: Explicit, readable code is better than clever one-liners. Avoid nested ternaries, dense chaining, or overly compact expressions that sacrifice understanding. 2. Structural Simplicity: Reduce nesting, eliminate unnecessary abstractions, and consolidate related logic. If a function needs more than three levels of indentation, redesign it. 3. Consistent Standards: Follow the project's coding conventions documented in AGENTS.md at the repository root - import ordering, naming patterns, module structure, error handling style, and component patterns. 4. Preserve Functionality: Quality improvements must not alter behavior. All outputs, side effects, and edge-case handling remain unchanged.

What to Look For

Naming and Intent

• Variables, functions, and classes that fail to communicate their purpose
• Abbreviated or single-letter names outside trivial loop counters
• Boolean variables or functions without is/has/should/can prefixes where appropriate
• Generic names like data, result, temp, item when a domain-specific name exists
• Inconsistent naming style within the same module (camelCase mixed with snake_case, etc.)

Complexity and Nesting

• Functions with more than three levels of indentation
• Long functions doing multiple unrelated things (violating single responsibility)
• Complex conditional chains that could be simplified with early returns, guard clauses, or lookup tables
• Nested ternary operators - always prefer if/else or switch for multiple conditions
• Deeply nested callbacks or promise chains that could be flattened

Redundancy and Dead Code

• Unused imports, variables, or parameters
• Commented-out code left in production files
• Redundant null checks, type assertions, or defensive code that the type system or caller contract already guarantees
• Unnecessary intermediate variables that add no clarity
• Comments that restate what the code obviously does

Error Handling

• Swallowed exceptions (empty catch blocks or except: pass)
• Overly broad catch clauses that mask real failures
• Missing error context (re-raising without original cause)
• Try/catch wrapping logic that cannot fail
• Inconsistent error handling strategy across the module

Project Standards Compliance

• Import ordering and grouping per AGENTS.md
• Module/function export patterns consistent with the project
• Proper type annotations where the project requires them
• React component patterns (if applicable): explicit Props types, proper hook usage
• File and directory organization matching project conventions

Review Checklist

• [ ] Read AGENTS.md to understand project-specific conventions before reviewing
• [ ] Verify all new/modified names clearly communicate intent
• [ ] Check that no function exceeds three levels of nesting
• [ ] Confirm each function has a single clear responsibility
• [ ] Flag any nested ternaries or dense one-liners that harm readability
• [ ] Identify unused code, redundant checks, and stale comments
• [ ] Verify error handling is consistent and informative
• [ ] Confirm adherence to project coding standards from AGENTS.md
• [ ] Ensure inline documentation exists for non-obvious logic (but not for obvious code)

Output Format

For each quality finding, provide:

**[QUALITY]** [file:line] - Brief description
  Issue: [What is wrong and why it matters]
  Suggestion: [Concrete, actionable improvement]
  Severity: CRITICAL | IMPROVEMENT | MINOR

Severity guide:

• CRITICAL: Actively harms maintainability, hides bugs, or violates project standards in a way that will cause problems.
• IMPROVEMENT: Code works but could be meaningfully cleaner, clearer, or more consistent.
• MINOR: Cosmetic or stylistic; mention only when it genuinely impacts readability. Do not nitpick.

When code quality is already good, state explicitly:

**[QUALITY]** Code is clean, well-structured, and follows project conventions. No issues found.

Code Reuse Review

A detailed reference for analyzing code reuse opportunities in recently modified code. Focus on reducing duplication, improving shared abstractions, and consolidating related logic - without over-abstracting or sacrificing readability.

Core Principles

1. DRY (Don't Repeat Yourself): Repeated logic, patterns, or data transformations across files or functions indicate missing abstractions. 2. Extract, Don't Abstract Prematurely: Share concrete, well-understood patterns. Avoid creating generic frameworks for two-use-case scenarios. 3. Respect AGENTS.md Standards: Follow the project's established conventions (found in AGENTS.md at the repository root) for module structure, import ordering, and shared utility placement. 4. Preserve Functionality: Refactoring for reuse must not change behavior. All original features, outputs, and edge-case handling remain intact.

What to Look For

Duplicate Code Blocks

• Near-identical functions or methods across files
• Copy-pasted logic with minor parameter differences
• Repeated validation, parsing, or formatting routines
• Similar error-handling patterns that could share a utility

Missing Shared Utilities

• String manipulation, date formatting, or data transformation repeated in multiple places
• Configuration or constant values hard-coded in several files instead of centralized
• Common I/O patterns (file reading, HTTP requests, DB queries) reimplemented per call site

Consolidation Opportunities

• Multiple functions that do slight variations of the same task - candidates for a single parameterized function
• Related helper functions scattered across modules that belong in a shared utility module
• Inline lambdas or closures duplicated across components

Over-Abstraction (Anti-Pattern)

• Shared base classes or generic wrappers introduced for only one or two consumers
• Abstraction layers that obscure simple operations
• "Util" modules that become dump-grounds for unrelated functions

Review Checklist

• [ ] Identify all blocks of duplicated or near-duplicated code in the changed files
• [ ] For each duplicate, determine whether extraction into a shared function/module is warranted (≥ 3 occurrences or high maintenance risk)
• [ ] Verify the project already has a utility or helper module; suggest placement there when it exists
• [ ] Confirm the proposed extraction preserves all call-site behavior
• [ ] Check that new shared code follows the naming and structure conventions in AGENTS.md
• [ ] Flag any existing abstractions in the codebase that the new code could leverage instead of reimplementing

Output Format

For each reuse finding, provide:

**[REUSE]** [file:line] - Brief description
  Duplicated in: [other-file:line], [another-file:line]
  Suggestion: Extract to `shared/utils.ts#functionName` (or appropriate module)
  Impact: Reduces maintenance surface, single source of truth for [logic description]

When no actionable reuse findings exist, state explicitly:

**[REUSE]** No significant duplication detected in the changed files.

Efficiency Review

A detailed reference for evaluating performance, resource usage, and algorithmic efficiency in recently modified code. Focus on real, measurable inefficiencies - not premature optimization or micro-benchmarks that do not matter at the project's scale.

Core Principles

1. Pragmatic Optimization: Fix inefficiencies that affect real users or real workloads. Do not optimize code paths that execute once at startup or handle trivial data volumes. 2. Algorithmic Awareness: Prefer better algorithms and data structures over micro-optimizations. An O(n²) loop over a growing dataset is a real problem; shaving nanoseconds off an O(n) loop is not. 3. Measure Before Prescribing: When recommending a change, explain why it matters at the expected scale. Cite the data size, call frequency, or latency target that makes the optimization worthwhile. 4. Preserve Functionality: Efficiency improvements must not change behavior. All outputs and side effects remain identical.

What to Look For

Algorithmic Complexity

• Nested loops over collections that grow with input size (O(n²) or worse)
• Linear search where a hash/set lookup would suffice
• Repeated sorting or filtering of the same data
• Recursive algorithms without memoization on overlapping subproblems
• Using arrays for membership checks instead of sets or maps

Unnecessary Work

• Recomputing values inside loops that could be computed once outside
• Performing I/O (file reads, network calls, DB queries) inside tight loops
• Loading entire datasets into memory when streaming or pagination is available
• Eagerly computing expensive results that may never be used (missing lazy evaluation)
• Serializing/deserializing data multiple times in the same pipeline

Resource Usage

• Unbounded memory growth (appending to lists without limits, caching without eviction)
• File handles, connections, or streams opened but not closed (missing finally/with/using/defer)
• Large object allocations in hot paths that could reuse buffers
• Spawning threads or processes without pooling or concurrency limits

Data Structure Choices

• Using a list where a set or map provides O(1) lookups
• Storing data in formats that require repeated parsing (e.g., stringified JSON accessed multiple times)
• Using mutable shared state where an immutable snapshot or copy-on-write pattern is safer and no slower
• Choosing a general-purpose collection when a specialized one (deque, priority queue, sorted set) better fits the access pattern

Database and I/O Patterns

• N+1 query patterns (fetching related records one-by-one inside a loop)
• Missing indices on frequently queried columns (when schema is visible)
• Fetching columns or rows not needed by the caller
• Synchronous blocking calls in async contexts

Review Checklist

• [ ] Identify any loops with O(n²) or worse complexity on non-trivial input sizes
• [ ] Check for repeated computation that could be hoisted or cached
• [ ] Verify I/O operations are batched and not performed in tight loops
• [ ] Confirm resources (connections, handles, streams) are properly closed
• [ ] Review data structure choices for appropriate access-pattern fit
• [ ] Look for N+1 query patterns or unnecessary full-table scans
• [ ] Validate that any suggested optimization is justified by expected scale

Output Format

For each efficiency finding, provide:

**[EFFICIENCY]** [file:line] - Brief description
  Issue: [What is inefficient and at what scale it matters]
  Suggestion: [Concrete fix with expected complexity improvement]
  Impact: HIGH (user-facing latency/cost) | MEDIUM (noticeable at scale) | LOW (minor, worth noting)

Impact guide:

• HIGH: Causes user-visible latency, excessive memory usage, or cost at current or near-term scale.
• MEDIUM: Becomes a problem as data or traffic grows; worth fixing proactively.
• LOW: Minor inefficiency; mention if the fix is trivial, otherwise skip.

When no efficiency concerns exist, state explicitly:

**[EFFICIENCY]** No significant performance or resource issues detected in the changed code.