playbooks

home / skills / sandraschi / advanced-memory-mcp / refactoring-specialist

refactoring-specialist skill

/skills/technical/refactoring-specialist

This skill guides safe code refactoring to improve quality and reduce debt using a structured playbook and evidence-based practices.

npx playbooks add skill sandraschi/advanced-memory-mcp --skill refactoring-specialist

Review the files below or copy the command above to add this skill to your agents.

Files (11)
SKILL.md
2.2 KB
---
name: refactoring-specialist
description: Code refactoring expert for improving code quality, reducing technical debt, and safe transformations
license: Proprietary
---

# Refactoring Specialist
> **Status**: ✅ Research complete
> **Last validated**: 2025-11-08
> **Confidence**: 🟡 Medium — Research-backed refactoring playbook – review annually

## How to use this skill
1. Clarify objectives via [modules/core-guidance.md](modules/core-guidance.md).
2. Assess technical debt with [modules/assessment-and-prioritization.md](modules/assessment-and-prioritization.md).
3. Select tactical moves from [modules/refactoring-patterns.md](modules/refactoring-patterns.md).
4. Build safety nets with [modules/safety-net-and-testing.md](modules/safety-net-and-testing.md).
5. For large initiatives, rely on [modules/architecture-modernization.md](modules/architecture-modernization.md).
6. Manage stakeholders using [modules/change-management-and-communication.md](modules/change-management-and-communication.md).
7. Track follow-ups in [modules/known-gaps.md](modules/known-gaps.md) and revisit [modules/research-checklist.md](modules/research-checklist.md) annually.

## Module overview
- [Core guidance](modules/core-guidance.md) — charter, success metrics, constraints.
- [Assessment & prioritization](modules/assessment-and-prioritization.md) — code smell catalog, impact scoring.
- [Refactoring patterns](modules/refactoring-patterns.md) — common transformations and IDE tooling.
- [Safety net & testing](modules/safety-net-and-testing.md) — characterization tests, automation.
- [Architecture modernization](modules/architecture-modernization.md) — modularization, strangler fig, domain alignment.
- [Change management & communication](modules/change-management-and-communication.md) — stakeholder buy-in, rollout communications.
- [Known gaps](modules/known-gaps.md) — research backlog.
- [Research checklist](modules/research-checklist.md) — annual refresh process.

## Research status
- Incorporates latest refactoring literature, debt metrics research, and evolutionary architecture practices.
- Next review due 2026-11-01 or earlier if major tooling innovations emerge.
- Known gaps track AI-assisted refactoring and socio-technical metrics pending further validation.

Overview

This skill is a code refactoring expert focused on improving code quality, reducing technical debt, and performing safe transformations in Python codebases. It provides a structured playbook for setting objectives, assessing debt, selecting refactoring tactics, and building safety nets. The guidance balances incremental fixes with larger architecture modernization when needed. It emphasizes measurable outcomes and repeatable processes.

How this skill works

The skill inspects code quality indicators, catalogs common code smells, and scores issues by risk and impact to prioritize work. It recommends concrete refactoring patterns and IDE/tooling tactics, and designs characterization tests and automation to ensure safety. For larger initiatives it outlines modularization and migration strategies while advising stakeholder communication and rollout plans.

When to use it

  • When technical debt is slowing feature delivery or causing frequent bugs.
  • Before a major feature or release to reduce regression risk and improve maintainability.
  • When onboarding new engineers who struggle to understand the codebase.
  • When preparing for architecture changes like breaking a monolith into services.
  • When you need a repeatable, audit-friendly refactoring plan for compliance or long-term maintenance.

Best practices

  • Define clear objectives and success metrics before changing code (e.g., reduced complexity, fewer incidents).
  • Prioritize refactors by risk, impact, and cost; fix high-impact low-cost items first.
  • Create characterization tests and CI checks to prevent regressions during refactors.
  • Make small, incremental changes with code review and feature-flagged rollouts where possible.
  • Document the rationale and keep a follow-up backlog for TODOs and known gaps.

Example use cases

  • Consolidating duplicated logic into a shared library to reduce bugs and simplify maintenance.
  • Replacing fragile conditional chains with a strategy pattern to improve extensibility.
  • Introducing automated tests and CI gates to a legacy module before refactoring it.
  • Applying the strangler fig pattern to incrementally extract components from a monolith.
  • Scoring and triaging code smells across the repository to build a prioritized refactor roadmap.

FAQ

How do you measure success after a refactor?

Use predefined metrics such as reduced cyclomatic complexity, lower bug rates, fewer hotfixes, improved test coverage, and cycle time for related changes.

How do you keep refactors from breaking production?

Use characterization tests, automated CI checks, small incremental changes, feature flags, staged rollouts, and thorough code review to mitigate regression risk.