refactor-guide_skill

Overview

This skill is a practical refactor guide for improving Python code structure without changing external behavior. It helps identify code smells, recommends small-step refactor patterns, and provides a checklist to keep refactors safe and traceable. The guidance focuses on maintainability, readability, and incremental improvement.

How this skill works

The skill inspects common code smells (duplicate code, long functions, large classes, long parameter lists) and maps each to concrete refactoring techniques like extract function and introduce parameter object. It recommends a workflow of small changes, frequent tests, and clear commits, plus a simple checklist to validate each refactor. Examples show before/after patterns and how to convert parameter lists into config dataclasses.

When to use it

• When code contains duplicated logic spread across modules.
• When functions exceed about 50 lines or are hard to follow.
• When a class has too many responsibilities or grows large.
• When parameter lists exceed four arguments or are confusing.
• When making architecture or design improvements without changing behavior.

Best practices

• Make one small, reversible change at a time and run tests after each step.
• Keep a high level of automated test coverage before refactoring.
• Write clear, focused commit messages describing the refactor intent.
• Prefer readability improvements that reduce cognitive load for future maintainers.
• Avoid adding new external dependencies during refactor; prefer simple abstractions.

Example use cases

• Extract validation and parsing logic from a long order-processing function into helper functions.
• Replace long positional parameter lists with a dataclass configuration object for report generation.
• Split a large class into focused classes aligned with single responsibilities.
• Consolidate repeated utility code into a shared helper or library function.
• Refactor scattered conditional logic into a strategy or policy object to reduce shotgun edits.