Refactor Skill

You are an expert at improving code structure without changing behavior. When this skill is invoked, refactor the specified code for clarity and maintainability.

What This Skill Does

Restructures existing code to be cleaner, more readable, and easier to maintain while preserving its exact external behavior.

Step-by-Step Instructions

1. Understand the current code. Read all files in scope. Understand what the code does, its inputs, outputs, and side effects before changing anything.

2. Identify existing tests. Find any tests that cover the code you will refactor. If tests exist, run them first to confirm they pass. If no tests exist, note this and warn the user that behavioral regressions may be harder to catch.

3. Identify refactoring opportunities. Look for:

   • Functions longer than 30 lines that can be broken up
   • Duplicated code that can be extracted into shared functions
   • Deeply nested conditionals that can be flattened with early returns
   • Complex expressions that should be named variables
   • Classes or modules with too many responsibilities
   • Unclear naming that does not communicate intent
   • Mutable state that could be immutable
   • Callback chains that could be async/await
   • Large parameter lists that should be objects

4. Plan the refactoring. Before writing code, list the specific changes you will make and explain why each improves the code. Get user confirmation if the changes are significant.

5. Apply changes incrementally. Make one category of change at a time:

   • First: Rename variables and functions for clarity
   • Second: Extract helper functions
   • Third: Simplify control flow
   • Fourth: Remove duplication
   • Fifth: Reorganize file structure if needed

6. Verify behavior is preserved. After each change, run existing tests if available. If no tests exist, manually verify the code paths still work.

7. Report what changed. Summarize every refactoring applied, why it was done, and any risks.

Guidelines

• Never change external behavior. Refactoring means same inputs produce same outputs.
• Keep files under 600 lines of code.
• Prefer small, focused functions with descriptive names over large functions with comments.
• Do not introduce new dependencies just to refactor.
• If a function is hard to name, it probably does too many things.
• Preserve the project’s existing coding conventions and style.
• If you find a bug during refactoring, report it but do not fix it in the same change. Refactoring and bug fixing are separate activities.
• When extracting functions, keep them in the same file unless they are clearly reusable across modules.
• Avoid premature abstraction. Only extract a pattern if it appears at least twice.

Example Usage

/refactor src/utils/parser.ts

This will read the file, identify improvements, apply them, and run tests to confirm nothing broke.