# Refactoring

> Use when refactoring code, or when an in-scope readability or design problem obstructs requested work. Improve code form without changing behavior.

- Skill: `jonfazzaro/refactoring` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jonfazzaro/refactoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jonfazzaro/refactoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jonfazzaro (https://skillmd.com/u/jonfazzaro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jonfazzaro/refactoring

---


## Context marker

📐

When the skill activates, begin the first commentary update with `📐` and a concise `Using refactoring ...` announcement. Do not repeat the marker on later updates unless another skill activates.

# Refactoring: Designing Your Code

Refactoring is how you design your code. It is not cleanup after the fact — it is an active design activity that shapes the code into a clear expression of its intent.

Work autonomously as much as possible. Start with the simplest thing or file and proceed to the more complex ones.

## Stages

1. Prep
2. Main Refactoring
3. Final Evaluation
4. Summary

## Specification Code Policy

Do not change specification code during refactoring, except:
- Renames that follow production code renames (imports, function calls)
- Import path updates if something moved

Never change specification assertions, specification data, or specification logic.

## 1. Prep

- Determine scope: use specified files, or identify related files (imports, shared functionality), or ask user
- Add files in scope to todo list
- Find or create ./spec.sh, verify all specs pass
- Review comments in scope; preserve required documentation, safety notes, licenses, and useful rationale, and remove only comments made redundant by clearer code

## 2. Main Refactoring

### Code Style

Prefer self-explanatory, readable code over comments.

- Use functional helper methods for clarity
- Remove dead code
- Extract paragraphs into methods
- Use better variable names
- Remove unused imports
- Remove unhelpful local variables
- Look for opportunities to simplify
- Use domain language - name things for what they ARE, not how they're implemented
- Keep consistent abstraction levels within methods

### Process

For each refactor:
1. Ensure all specs pass
2. Choose and perform the simplest possible refactoring (one at a time)
3. Ensure all specs pass after the change
4. Commit each successful refactor as `design: <refactoring>` unless repository conventions require another format.
   Prefer small granular commits. If applying the same refactoring pattern to multiple locations, change one location at a time and commit each separately.
5. Provide a status update after each refactor

## 3. Final Evaluation

When you see no more in-scope refactoring opportunities, say "🔍 Entering final evaluation."

Shift focus from implementation to one bounded critical pass over the requested and touched scope.

Re-read Code Style guidelines. Look at each file in scope. Consider blind spots - what improvements haven't we even considered that would make the code better, easier, more maintainable?

For each file, look for one concrete in-scope issue introduced, exposed, or obstructing the requested work. If you find one:
1. Fix it using the same refactoring process (test, change, test, commit)
2. Look again; fixing one thing often reveals the next

Stop after the bounded pass finds no concrete in-scope issue. Report unrelated opportunities instead of expanding the task.

## 4. Summary

Provide a high-level summary of the refactoring:
- List each file that was touched
- Describe the key improvements made in each file

## Language-Specific

For Java: See [references/java.md](references/java.md)