refactor-clean
Use when code has grown complex, duplicated, or cluttered — clean up structure and remove dead code without changing observable behavior
Install
npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/development/refactor-clean
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
git clone https://github.com/drvoss/everything-copilot-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Refactor & Clean Code
When to Use
- Code is correct but hard to read, modify, or extend
- Duplicated logic exists across multiple files
- Functions or classes have grown too large
- Preparing code for a new feature that requires structural changes
- After a rapid prototype that needs production-quality cleanup
Prerequisites
- Existing tests that cover the code to refactor (add tests first if missing)
- All tests passing before starting
- Code committed so you can revert if needed
Workflow
1. Identify Code Smells
# Find long files (likely doing too much)
Get-ChildItem -Recurse -Include *.ts,*.js,*.py,*.go | Where-Object { (Get-Content $_.FullName | Measure-Object -Line).Lines -gt 300 } | Select-Object FullName, @{N='Lines';E={(Get-Content $_.FullName | Measure-Object -Line).Lines}}
# Find duplicated string patterns
grep -rn "pattern-you-suspect-is-duplicated" src/ --include="*.ts"
# Find functions with too many parameters (>4 is a smell)
grep -n "function.*,.*,.*,.*," src/**/*.ts
Common smells to look for:
- Long functions (>40 lines) — extract smaller functions
- Duplicate code — extract shared utility
- Deep nesting (>3 levels) — use early returns or extract
- God objects — split into focused classes/modules
- Primitive obsession — introduce domain types
- Feature envy — move logic to the class that owns the data
2. Establish a Safety Net
# Run existing tests and record baseline
npm test 2>&1 | Tee-Object -Variable baseline
echo $baseline | Select-Object -Last 5
# If coverage is low, write characterization tests first
npm test -- --coverage --collectCoverageFrom="src/module-to-refactor.ts"
3. Plan the Refactoring
Before touching code, decide on the transformation:
- Extract Function — pull a block into a named function
- Extract Module — move related functions to a new file
- Rename — improve names for clarity
- Inline — remove unnecessary indirection
- Replace Conditional with Polymorphism — use strategy pattern
- Introduce Parameter Object — group related parameters
4. Make Small, Incremental Changes
Each change should be:
- A single refactoring operation
- Followed by running tests
- Committed if tests pass
# After each refactoring step
npm test 2>&1 | Select-Object -Last 10
# If tests break, revert and try a smaller step
git checkout -- src/module-to-refactor.ts
5. Verify Behavior is Preserved
# Full test suite must still pass
npm test
# Compare coverage — it should not decrease
npm test -- --coverage
6. Slim a Fresh Diff by Ablation (optional)
When the code to clean is the current PR or working-tree change rather than old code, cut it down
to the smallest correct diff (concept adapted from antfu/skills antfu-simplify):
- Write the change's goal in one sentence. Every remaining line must be explained by it.
- List each piece the diff adds — helper, parameter, branch, type, file, dependency, comment, test.
- For each piece, try deleting, inlining, or hardcoding it and run the focused checks. Keep it if something that matters breaks. If no check covers it, keep it unless you can show the case it guards is unreachable.
- Revert drive-by edits that the goal does not explain. Do not change behavior or public APIs.
- Report what was cut or kept and why, with
git diff --statbefore and after.
Cut speculative options, pass-through wrappers, one-use helpers, and guards against impossible input. Keep handling for real edge cases and the general fix over a special case.
Examples
Extract Repeated Logic
// BEFORE: duplicated validation in multiple handlers
function createUser(data) {
if (!data.email || !data.email.includes('@')) throw new Error('Invalid email');
// ... create logic
}
function updateUser(data) {
if (!data.email || !data.email.includes('@')) throw new Error('Invalid email');
// ... update logic
}
// AFTER: extracted to a shared validator
function validateEmail(email: string): void {
if (!email || !email.includes('@')) throw new Error('Invalid email');
}
function createUser(data) { validateEmail(data.email); /* ... */ }
function updateUser(data) { validateEmail(data.email); /* ... */ }
Flatten Deep Nesting with Early Returns
// BEFORE
function process(input) {
if (input) {
if (input.isValid) {
if (input.data.length > 0) {
return transform(input.data);
}
}
}
return null;
}
// AFTER
function process(input) {
if (!input || !input.isValid || input.data.length === 0) return null;
return transform(input.data);
}
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'm not sure what this code does, but it looks unused" | If you're not sure, don't remove it. Use git blame to understand the context first. (Chesterton's Fence) |
| "I'll add a feature while refactoring" | Separate refactoring from feature work. Mixing the two makes debugging impossible. |
| "Tests still pass, so the refactor is correct" | Tests must exist before refactoring to have any meaning. If not, write them first. |
| "TypeScript isn't warning, so it's safe to delete" | Dynamic imports, reflection, and external references are invisible to the type system. |
Red Flags
- Refactoring commit contains feature changes
- Dead code removed without any tests
- Type errors suppressed with
// @ts-ignoreoranytypes - No verification that the same tests pass before and after refactoring
- Complex code left with "clean up later" TODO and no action
Verification
-
npm testpasses identically before and after the refactor - Removed code confirmed as unused (
grep -rnor IDE reference search) - Complexity metrics improved (reduced function length, nesting depth)
- Refactor commit contains no feature changes (commit message:
refactor:) - PR describes the motivation for the refactor (why this code was cleaned up)
Tips
- Never refactor and add features in the same commit — keep them separate
- Use
exploreagent to understand call graphs before renaming or moving functions - Use
grepto find all callers before changing a function signature - If tests are missing, write them first — refactoring without tests is gambling
- Commit after every successful small refactoring — you can always squash later
- The best refactoring is deleting code: look for dead code with
grepand remove it
Files (everything-copilot-cli)
-
SKILL.md 6.7 KB
--- name: refactor-clean license: MIT description: Use when code has grown complex, duplicated, or cluttered — clean up structure and remove dead code without changing observable behavior metadata: category: development agent_type: general-purpose --- # Refactor & Clean Code ## When to Use - Code is correct but hard to read, modify, or extend - Duplicated logic exists across multiple files - Functions or classes have grown too large - Preparing code for a new feature that requires structural changes - After a rapid prototype that needs production-quality cleanup ## Prerequisites - Existing tests that cover the code to refactor (add tests first if missing) - All tests passing before starting - Code committed so you can revert if needed ## Workflow ### 1. Identify Code Smells ```powershell # Find long files (likely doing too much) Get-ChildItem -Recurse -Include *.ts,*.js,*.py,*.go | Where-Object { (Get-Content $_.FullName | Measure-Object -Line).Lines -gt 300 } | Select-Object FullName, @{N='Lines';E={(Get-Content $_.FullName | Measure-Object -Line).Lines}} # Find duplicated string patterns grep -rn "pattern-you-suspect-is-duplicated" src/ --include="*.ts" # Find functions with too many parameters (>4 is a smell) grep -n "function.*,.*,.*,.*," src/**/*.ts ``` Common smells to look for: - **Long functions** (>40 lines) — extract smaller functions - **Duplicate code** — extract shared utility - **Deep nesting** (>3 levels) — use early returns or extract - **God objects** — split into focused classes/modules - **Primitive obsession** — introduce domain types - **Feature envy** — move logic to the class that owns the data ### 2. Establish a Safety Net ```powershell # Run existing tests and record baseline npm test 2>&1 | Tee-Object -Variable baseline echo $baseline | Select-Object -Last 5 # If coverage is low, write characterization tests first npm test -- --coverage --collectCoverageFrom="src/module-to-refactor.ts" ``` ### 3. Plan the Refactoring Before touching code, decide on the transformation: - **Extract Function** — pull a block into a named function - **Extract Module** — move related functions to a new file - **Rename** — improve names for clarity - **Inline** — remove unnecessary indirection - **Replace Conditional with Polymorphism** — use strategy pattern - **Introduce Parameter Object** — group related parameters ### 4. Make Small, Incremental Changes Each change should be: 1. A single refactoring operation 2. Followed by running tests 3. Committed if tests pass ```powershell # After each refactoring step npm test 2>&1 | Select-Object -Last 10 # If tests break, revert and try a smaller step git checkout -- src/module-to-refactor.ts ``` ### 5. Verify Behavior is Preserved ```powershell # Full test suite must still pass npm test # Compare coverage — it should not decrease npm test -- --coverage ``` ### 6. Slim a Fresh Diff by Ablation (optional) When the code to clean is the current PR or working-tree change rather than old code, cut it down to the smallest correct diff (concept adapted from antfu/skills `antfu-simplify`): 1. Write the change's goal in one sentence. Every remaining line must be explained by it. 2. List each piece the diff adds — helper, parameter, branch, type, file, dependency, comment, test. 3. For each piece, try deleting, inlining, or hardcoding it and run the focused checks. Keep it if something that matters breaks. If no check covers it, keep it unless you can show the case it guards is unreachable. 4. Revert drive-by edits that the goal does not explain. Do not change behavior or public APIs. 5. Report what was cut or kept and why, with `git diff --stat` before and after. Cut speculative options, pass-through wrappers, one-use helpers, and guards against impossible input. Keep handling for real edge cases and the general fix over a special case. ## Examples ### Extract Repeated Logic ```typescript // BEFORE: duplicated validation in multiple handlers function createUser(data) { if (!data.email || !data.email.includes('@')) throw new Error('Invalid email'); // ... create logic } function updateUser(data) { if (!data.email || !data.email.includes('@')) throw new Error('Invalid email'); // ... update logic } // AFTER: extracted to a shared validator function validateEmail(email: string): void { if (!email || !email.includes('@')) throw new Error('Invalid email'); } function createUser(data) { validateEmail(data.email); /* ... */ } function updateUser(data) { validateEmail(data.email); /* ... */ } ``` ### Flatten Deep Nesting with Early Returns ```typescript // BEFORE function process(input) { if (input) { if (input.isValid) { if (input.data.length > 0) { return transform(input.data); } } } return null; } // AFTER function process(input) { if (!input || !input.isValid || input.data.length === 0) return null; return transform(input.data); } ``` ## Common Rationalizations | Rationalization | Reality | |----------------|---------| | "I'm not sure what this code does, but it looks unused" | If you're not sure, don't remove it. Use `git blame` to understand the context first. (Chesterton's Fence) | | "I'll add a feature while refactoring" | Separate refactoring from feature work. Mixing the two makes debugging impossible. | | "Tests still pass, so the refactor is correct" | Tests must exist before refactoring to have any meaning. If not, write them first. | | "TypeScript isn't warning, so it's safe to delete" | Dynamic imports, reflection, and external references are invisible to the type system. | ## Red Flags - Refactoring commit contains feature changes - Dead code removed without any tests - Type errors suppressed with `// @ts-ignore` or `any` types - No verification that the same tests pass before and after refactoring - Complex code left with "clean up later" TODO and no action ## Verification - [ ] `npm test` passes identically before and after the refactor - [ ] Removed code confirmed as unused (`grep -rn` or IDE reference search) - [ ] Complexity metrics improved (reduced function length, nesting depth) - [ ] Refactor commit contains no feature changes (commit message: `refactor:`) - [ ] PR describes the motivation for the refactor (why this code was cleaned up) ## Tips - **Never refactor and add features in the same commit** — keep them separate - Use `explore` agent to understand call graphs before renaming or moving functions - Use `grep` to find all callers before changing a function signature - If tests are missing, write them first — refactoring without tests is gambling - Commit after every successful small refactoring — you can always squash later - The best refactoring is deleting code: look for dead code with `grep` and remove it
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.