Refactor and Clean Code for Maintainability

Refactor and Clean Code is a skill that positions the model as a code refactoring expert in clean code principles, SOLID design patterns and modern software engineering practice. It analyzes the code you provide and refactors it to improve quality, maintainability and performance, focusing on practical improvements that enhance code quality without over-engineering.

The workflow is incremental: assess code smells, dependencies and risky hotspots; propose a refactor plan in small steps; apply changes in slices while keeping behavior stable; and update tests and verify regressions. The analysis phase looks for three kinds of problems. Code smells include long methods over 20 lines, large classes over 200 lines, duplicate blocks, dead code, complex conditionals and nested loops, magic numbers, poor naming, tight coupling and missing abstractions. SOLID violations are checked one principle at a time. Performance issues include O(n squared) or worse algorithms, unnecessary object creation, possible memory leaks, blocking operations and missing caching.

The refactoring strategy starts with immediate fixes that are high impact and low effort: extract magic numbers to constants, improve names, remove dead code, simplify boolean expressions and extract duplicate code into functions. It then moves to method extraction, class decomposition (separate responsibilities, interfaces for dependencies, dependency injection, composition over inheritance) and pattern application (Factory, Strategy, Observer, Repository and Decorator). Method extraction looks like this:

# Before
def process_order(order):
    # 50 lines of validation
    # 30 lines of calculation
    # 40 lines of notification

# After
def process_order(order):
    validate_order(order)
    total = calculate_order_total(order)
    send_order_notifications(order, total)

The playbook adds decision frameworks. A metrics matrix gives Good, Warning and Critical thresholds, for example cyclomatic complexity under 10 is good and over 15 is critical, test coverage above 80 percent is good and below 60 percent is critical, and code duplication under 3 percent is good and over 5 percent is critical. A refactoring priority formula weighs business value and technical debt against effort and risk, and a decision tree ranks debt from production bugs (critical) down to backlog items. It also covers modern tooling: AI-assisted pull request review, Ruff, mypy and coverage configuration for Python, ESLint with SonarJS and security plugins for TypeScript, Sourcery rules, SonarQube quality gates, Semgrep and CodeQL. Further sections cover testing strategy, before and after comparisons, a migration guide with a backward-compatibility adapter, algorithm and caching optimizations, and a quality checklist.

The worked examples are concrete. For the Single Responsibility Principle, a UserManager that validates, saves, emails, logs and updates a cache is split into a validator, a repository, an email service, an activity logger and a coordinating UserService. For the Open/Closed Principle, a DiscountCalculator that branches on discount type is replaced by an abstract DiscountStrategy that new discount types extend. A full scenario takes a 500-line monolithic order system, which mixes validation (100 lines), database operations (150), business logic (100), email notifications (80) and logging (70), and separates it into domain entities, repository contracts, a MySQL repository, validators and services. The clean code principles listed are meaningful names, functions that do one thing well, no side effects, consistent abstraction levels, DRY and YAGNI, and the testing strategy asks for all public methods tested, edge cases covered, error conditions verified and performance benchmarks included. The refactored code uses specific exception classes, fails fast with clear messages, and documents functions with typed docstrings. The tooling examples set Ruff to a line length of 100, mypy to strict mode, ESLint to a complexity limit of 10, at most 20 lines per function and at most 3 parameters, SonarQube quality gates with a 300 second timeout, an 80 percent coverage threshold and A ratings, Semgrep rules for SQL injection risk and hardcoded secrets, and CodeQL with the security-extended and security-and-quality query suites. Performance examples replace a nested O(n squared) loop with a dictionary lookup and add lru_cache with a maxsize of 128.

Use it when refactoring tangled or hard-to-maintain code, reducing duplication, complexity or code smells, improving testability and design consistency, or preparing modules for new features safely.

Do not use it for a small one-line fix, when refactoring is prohibited by a change freeze, or when the request is documentation only. The safety rules are to avoid changing external behavior without explicit approval and to keep diffs reviewable with passing tests. The skill also says not to treat its output as a substitute for environment-specific validation, testing or expert review, and to stop and ask when inputs, permissions, safety boundaries or success criteria are missing.

The input is the code to refactor, supplied as the skill's requirements arguments. The short output format is a summary of issues and target areas, a refactor plan with ordered steps, proposed changes with expected impact, and test and verification notes. The fuller playbook output has eight parts: an analysis summary, a refactoring plan with effort estimates, refactored code with explanatory comments, a test suite, a migration guide, a metrics report, AI review results and a link to quality dashboard results. Issues are rated Critical, High, Medium or Low, from security vulnerabilities and data corruption down to style inconsistencies.

The playbook references GitHub Actions for AI-assisted review (GitHub Copilot Autofix, CodeRabbit and PR-Agent), Ruff, mypy and coverage settings, ESLint, Sourcery, SonarQube, Semgrep and CodeQL. These appear as example configurations rather than requirements.

Developers and reviewers who need to clean up existing code in small, reviewable steps, with behavior preserved and tests updated as they go.