refactoring-advisor_skill

Overview

This skill analyzes PHP and CakePHP code to identify refactoring opportunities that improve maintainability, performance, and adherence to best practices. It surfaces code smells, suggests design pattern applications, and recommends focused performance and database refactors. Recommendations are actionable and prioritized to help teams reduce technical debt quickly.

How this skill works

The skill inspects source files for common indicators: long methods, large classes, duplicated code, deep nesting, high cyclomatic complexity, and excessive parameters. It maps findings to concrete refactors—method extraction, repositories, service layers, factories, behaviors, and caching—and provides sample code patterns and migration steps. Results include a prioritized list of candidates with suggested tests and safety checks to validate changes.

When to use it

• Before a major feature change or release to reduce regression risk
• When code reviews repeatedly flag the same maintainability issues
• To remediate performance hotspots (N+1 queries, slow queries, repeated expensive calculations)
• When onboarding new developers to identify complexity hotspots
• During a technical debt cleanup sprint to prioritize impactful refactors

Best practices

• Prioritize refactors that reduce risk: security, performance, and frequently changed code first
• Extract small, well-tested units (services, repositories, components) rather than large rewrites
• Introduce patterns incrementally and keep controllers thin by moving business logic to services
• Replace duplicated logic with shared helpers or behaviors to centralize rules
• Add or update automated tests before refactoring and use feature toggles for risky changes

Example use cases

• Split a 200-line controller action into validation, calculation, persistence, and notification methods
• Replace repeated CSV export code with a reusable Controller Component
• Convert direct table queries into a repository layer to centralize query logic
• Fix N+1 query patterns by adding contain() calls or optimized joins and aggregate queries
• Introduce caching for expensive monthly statistics endpoints to reduce response time