discountry/ritmex-skills/refactor

Refactor Skill

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler

Iteratively improve code for readability, maintainability, and reusability without breaking observable behavior. Apply the principles of Refactoring (Fowler), Clean Code (Martin), and The Art of Readable Code (Boswell & Foucher).

Refactoring is not rewriting. Change structure, not behavior.

Before Touching Anything

1. Understand what the code actually does and where its boundaries are.
2. Identify the highest-pain smells — prioritize ruthlessly.
3. If tests are absent, flag it. Refactoring without a safety net is high-risk.
4. Propose an incremental plan. Never refactor everything in one pass.

Core Principles

SRP everywhere — functions, classes, modules, files each own exactly one responsibility.

Size as a signal, not a rule — functions trending past ~30 lines and files past ~300 lines are worth questioning. But complexity varies: a genuinely complex algorithm may justify more lines than a simple utility. Use size as a prompt to ask "is this doing too much?" not as a threshold to mechanically split.

Names over comments — a name that requires a comment to explain is a name that needs replacing. Reserve comments for why, never what.

DRY without fanaticism — eliminate duplication by extracting shared abstractions, but never force unrelated concepts into one abstraction just because they look alike. The wrong abstraction is worse than duplication.

Low coupling, high cohesion — depend on abstractions, inject dependencies, keep things that change together physically together.

Guard clauses over nesting — return early, validate at the top, keep the happy path flat.

No magic values — every domain-meaningful literal gets a named constant.

Refactoring Moves (Fowler Catalog)

Name the move when applying it — shared vocabulary improves code review:

Code Smells → Fix

Design Patterns

Apply only when the problem genuinely exists. Preferred patterns for decoupling and flexibility: Strategy, Factory, Observer, Repository, Decorator, Command.

Simpler is always preferred. A pattern without a problem is over-engineering. Real-world complexity sometimes justifies less abstraction, not more.

Iterative Protocol

One smell → one fix → verify → commit (with the move name in the message) → repeat.

Never mix refactoring commits with feature commits.

Output Format

1. Diagnosis — smells found, ranked by severity
2. Plan — moves to apply, in order
3. Refactored Code — before/after, clearly labeled
4. Rationale — one sentence per significant change
5. Behavior preserved — explicit confirmation

Scope large codebases to one module or function per response. Say so when doing this.