refactoring · git:20260519.40bb110 · 2026-05-19 · sha256 4cd75c7014402347
refactoring git:20260519.40bb110A
Immutable. This exact content never changes and is served at /api/v1/blob/4cd75c7014402347.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_aiogg6w3nv5iqhnk/4cd75c701440234735329a20bf26efcded1956c428e8604642fe4af0fb67ec11.json
Then /plugin install refactoring@markdownregistry-aiogg6w3nv5iqhnk in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: refactoring
description: Safe, test-backed code restructuring in small steps.
tier: practical
category: workflow
created_by: human
platforms: [windows, macos, linux]
tags: [refactoring, quality, debt]
author: Andreas Wasita (@andreaswasita)
---
# Refactoring Skill
Restructures existing code without changing behavior, in small atomic steps each backed by a green test suite. Does NOT add features in the same change — refactoring and feature work travel in separate PRs.
## When to Use
- A function, class, or file has grown unmanageable.
- Duplication is spreading across modules.
- The `demand-elegance` skill flagged a hacky solution.
- Names no longer reflect purpose after a domain shift.
- Before adding a new feature into a messy area.
- NOT when there is no test coverage and the change is high-risk — write tests first.
## Prerequisites
- Working test suite (or willingness to write characterization tests first).
- `git` for atomic commits per transformation.
- The `view`, `edit`, `grep`, and `glob` Copilot tools.
- A baseline run of the test suite passing (proven, not assumed).
## How to Run
```text
1. Run the full test suite. Confirm green baseline.
2. If no tests cover the target, write characterization tests; commit separately.
3. Apply one named transformation.
4. Re-run tests. If red, revert.
5. Commit. Repeat for next transformation.
6. Final pass: full suite + review of the whole diff.
```
## Quick Reference
| Smell | Refactoring |
|---|---|
| Long function (>30 lines) | Extract smaller, named functions |
| Duplicate code | Extract shared function or module |
| Deep nesting (>3 levels) | Early returns, extract conditions |
| God class / file | Split by responsibility |
| Primitive obsession | Introduce domain types |
| Feature envy | Move logic to the class that owns the data |
| Long parameter list (>4) | Introduce parameter object |
| Dead code | Delete it — version control remembers |
## Procedure
### Step 1: Establish the Safety Net
Identify tests covering the target with `grep` / `glob`. Run them via the `powershell` tool. If they fail or do not exist, write characterization tests first and commit them in a separate commit before any refactor.
### Step 2: Name the Transformation
Each step in the refactor must have a name from the rubric above ("extract method", "introduce parameter object", "rename for clarity"). If you cannot name it, you are freelancing — stop.
### Step 3: One Transformation, One Commit
For each step:
1. Apply the change with the `edit` tool.
2. Run the full test suite.
3. If red, revert immediately.
4. If green, commit with message `refactor: <named transformation>`.
```text
refactor: extract validateInput() from handleRequest()
refactor: rename UserManager to UserRepository
refactor: move email logic to NotificationService
refactor: delete unused formatLegacyDate()
```
### Step 4: Verify the Whole
Run the full suite a final time. Review the cumulative diff (`git diff main`). Ask: is the result actually clearer, or just rearranged? If not clearer, revert.
## Pitfalls
- **DO NOT** refactor without a green test baseline. You are gambling, not refactoring.
- **DO NOT** mix refactor and feature work in one PR. Reviewers cannot tell signal from noise.
- **DO NOT** rename a symbol without searching every reference first (`grep` on the symbol).
- **DO NOT** rewrite for a hypothetical future ("we might need this pluggable"). Refactor for today.
- **DO NOT** big-bang refactor across the whole repo in one commit — small atomic steps, always.
## Verification
- [ ] Test suite is green before the first transformation.
- [ ] Test suite is green after every commit.
- [ ] Each commit is named `refactor: <transformation>`.
- [ ] No public API changed (or, if it did, callers were updated in the same PR).
- [ ] Final diff is meaningfully clearer than the starting code.