refactoring
/refactoring
Technical debt remediation and code restructuring workflow. Use when improving code structure, reducing complexity, extracting abstractions, or paying down accumulated technical debt.
- Author
- ar4mirez ↗
- Repository
- samuel ↗
- Licence
- MIT
- Last repository change
- 29.04.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Technical debt remediation and code restructuring workflow. Use when improving code structure, reducing complexity, extracting abstractions, or paying down accumulated technical debt.
Original author description
Technical debt remediation and code restructuring workflow. Use when improving code structure, reducing complexity, extracting abstractions, or paying down accumulated technical debt.
How it works
- When to Use
- Refactoring Principles
- Prerequisites
- Refactoring Process
- Phase 1: Identify Candidates
- Phase 2: Impact Analysis
- Phase 3: Plan Refactoring
- Phase 4: Add Safety Net
- Phase 5: Execute Incrementally
- Phase 6: Validate & Document
SKILL.md preview
---
name: refactoring
description: |
Technical debt remediation and code restructuring workflow. Use when improving
code structure, reducing complexity, extracting abstractions, or paying down
accumulated technical debt.
license: MIT
metadata:
author: samuel
version: "1.0"
category: workflow
---
# Refactoring Skill
Structured approach to technical debt remediation. Improve code structure while maintaining behavior through incremental, safe changes.
---
## When to Use
| Trigger | Description |
|---------|-------------|
| **Guardrail Violations** | Functions >50 lines, files >300 lines |
| **Complexity Threshold** | Cyclomatic complexity >10 |
| **Code Duplication** | Same logic in 3+ places |
| **Quarterly Review** | Regular technical debt assessment |
| **Pre-Feature** | Before adding features to messy code |
| **Post-Incident** | After bugs caused by confusing code |
---
## Refactoring Principles
### Golden Rules
1. **Behavior Preservation**: Output unchanged after refactoring
2. **Small Steps**: One change at a time
3. **Test First**: Ensure tests exist before changing
4. **Incremental**: Commit after each successful change
5. **Reversible**: Easy to roll back if issues arise
### When NOT to Refactor
- During active incident response
- Without test coverage
- When deadline is imminent
- If no clear improvement goal
---
## Prerequisites
Before starting:
- [ ] Code compiles and all tests pass
- [ ] Test coverage exists for target code (>60%)
- [ ] Clear refactoring goal defined
- [ ] Time allocated (refactoring always takes longer)
- [ ] Git working directory is clean
---
## Refactoring Process
```
Phase 1: Identify Candidates
↓
Phase 2: Impact Analysis
↓
Phase 3: Plan Refactoring
↓
Phase 4: Add Safety Net
↓
Phase 5: Execute Incrementally
↓
Phase 6: Validate & Document
```
---
## Phase 1: Identify Candidates
### 1.1 Automated Detection
**Long Functions** (>50 lines):
```bash
# Find functions over 50 lines (varies by language)
# Example: use linter rules or IDE features
```
**Long Files** (>300 lines):
```bash
# Find files over 300 lines
find src -name "*.ts" -exec wc -l {} \; | awk '$1 > 300'
find src -name "*.py" -exec wc -l {} \; | awk '$1 > 300'
```
**High Complexity**:
```bash
# Use complexity analyzers
npx escomplex src/**/*.ts
python -m mccabe src/**/*.py
```
### 1.2 Code Smells
| Smell | Signs | Priority |
|-------|-------|----------|
| **Long Method** | >50 lines, multiple responsibilities | High |
| **Large Class** | >300 lines, low cohesion | High |
| **Feature Envy** | Method uses other class more than own | Medium |
| **Data Clumps** | Same group of variables together | Medium |
| **Primitive Obsession** | Overuse of primitives vs objects | Medium |
| **Switch Statements** | Large switch blocks | Low |
| **Speculative Generality** | Unused abstractions | Low |
### 1.3 Candidate List
Document identified candidates:
```markdown
## Refactoring Candidates
### High Priority
| File | Issue | Lines | Impact |
|------|-------|-------|--------|
| src/services/order.ts | Long method: processOrder | 120 → 50 | High |
| src/api/users.ts | Large file | 450 → 200 | High |
| src/utils/validation.ts | Duplication | N/A | Medium |
### Medium Priority
| File | Issue | Lines | Impact |
|------|-------|-------|--------|
| src/models/product.ts | Feature envy | N/A | Medium |
| src/services/email.ts | Complex conditionals | N/A | Medium |
```
---
## Phase 2: Impact Analysis
### 2.1 Dependency Mapping
For each candidate, identify:
```
Target: src/services/order.ts
Dependencies (imports from):
- src/models/order.ts
- src/services/inventory.ts
- src/services/payment.ts
Dependents (imported by):
- src/api/orders.ts
- src/workers/orderProcessor.ts
- tests/services/order.test.ts
Impact radius: 5 files
Risk level: Medium
```
### 2.2 Risk Assessment
| Factor | Low | Medium | High |
|--------|-----|--------|------|
| Test coverage | >80% | 60-80% | <60% |
| Dependents | <3 | 3-10 | >10 |
| Business criticality | Non-critical | Important | Critical path |
| Complexity | Simple rename | Extract method | Architecture change |
### 2.3 Risk Matrix
```
Low Effort High Effort
┌────────────┬────────────┐
High Value │ DO FIRST │ PLAN │
│ │ CAREFULLY │
├────────────┼────────────┤
Low Value │ QUICK WIN │ AVOID │
│ │ │
└────────────┴────────────┘
```
---
## Phase 3: Plan Refactoring
### 3.1 Choose Refactoring Technique
| Smell | Technique | Description |
|-------|-----------|-------------|
| Long method | Extract Method | Pull out logical chunks |
| Large class | Extract Class | Split by responsibility |
| Feature envy | Move Method | Move to appropriate class |
| Data clumps | Extract Parameter Object | Group related params |
| Duplicated code | Extract to shared function | DRY principle |
| Complex conditional | Replace with polymorphism | Strategy pattern |
| Long parameter list | Introduce Parameter Object | Create wrapper class |
### 3.2 Step-by-Step Plan
Example: Extract Method from Long Function
```markdown
## Refactoring Plan: processOrder()
### Goal
Reduce processOrder() from 120 lines to <50 lines
### Steps
1. [ ] Add characterization tests for current behavior
2. [ ] Extract validateOrder() (lines 15-35)
3. [ ] Verify tests pass
4. [ ] Commit: "refactor: extract validateOrder"
5. [ ] Extract calculateTotals() (lines 40-65)
6. [ ] Verify tests pass
7. [ ] Commit: "refactor: extract calculateTotals"
8. [ ] Extract processPayment() (lines 70-95)
9. [ ] Verify tests pass
10. [ ] Commit: "refactor: extract processPayment"
11. [ ] Extract sendConfirmation() (lines 100-115)
12. [ ] Verify tests pass
13. [ ] Commit: "refactor: extract sendConfirmation"
14. [ ] Final cleanup and documentation
15. [ ] Commit: "refactor: cleanup processOrder"
### Expected Result
- processOrder(): 120 → 25 lines
- New methods: 4
- Total lines: +10 (net increase for clarity)
```
---
## Phase 4: Add Safety Net
### 4.1 Characterization Tests
Before refactoring, add tests that capture current behavior:
```typescript
describe('processOrder - characterization tests', () => {
it('should match current behavior for valid order', () => {
const order = createValidOrder();
const result = processOrder(order);
// Capture current output exactly
expect(result).toMatchSnapshot();
});
it('should match current behavior for edge cases', () => {
const edgeCases = [
createEmptyOrder(),
createMaxItemOrder(),
createDiscountedOrder(),
];
edgeCases.forEach(order => {
expect(processOrder(order)).toMatchSnapshot();
});
});
});
```
### 4.2 Coverage Check
Ensure adequate coverage before proceeding:
```bash
# Check coverage for target file
npm test -- --coverage --collectCoverageFrom="src/services/order.ts"
```
**Minimum Coverage**: 60% before refactoring (prefer >80%)
### 4.3 Checkpoint Commit
Create a checkpoint before starting:
```bash
git add .
git commit -m "chore: checkpoint before refactoring processOrder"
```
---
## Phase 5: Execute Incrementally
### 5.1 One Change at a Time
**Bad**: Multiple changes in one commit
```bash
# Too much at once - hard to debug if tests fail
git commit -m "refactor: refactor entire order module"
```
**Good**: Atomic changes
```bash
git commit -m "refactor(order): extract validateOrder method"
git commit -m "refactor(order): extract calculateTotals method"
git commit -m "refactor(order): extract processPayment method"
```
### 5.2 Red-Green-Refactor
For each change:
```
1. Run tests → PASS (green)
2. Make one refactoring change
3. Run tests → Should still PASS (green)
4. If FAIL (red) → Revert and try smaller change
5. If PASS → Commit
6. Repeat
```
### 5.3 Common Refactoring Patterns
See `references/process.md` for detailed code examples including:
- Extract Method pattern
- Extract Class pattern
- Replace Conditional with Polymorphism pattern
---
## Phase 6: Validate & Document
### 6.1 Final Validation
- [ ] All tests pass
- [ ] Coverage maintained or improved
- [ ] No new linter warnings
- [ ] Performance unchanged (or improved)
- [ ] Behavior identical (check snapshots)
### 6.2 Document Changes
**Update patterns.md** (if new pattern emerged):
```markdown
## Order Processing Pattern
Orders are processed through composable steps:
1. validateOrder() - Input validation
2. calculateTotals() - Price calculations
3. processPayment() - Payment handling
4. sendConfirmation() - Notifications
```
**Create memory entry** (if significant):
```markdown
# Refactoring: Order Processing
**Date**: 2025-01-15
**Files**: src/services/order.ts
## Before
- Single 120-line function
- Difficult to test
- Hard to modify
## After
- 5 focused functions (<30 lines each)
- Easier to test
- Clear responsibilities
## Lessons
- Extract Method is low-risk, high-reward
- Characterization tests prevented regressions
```
### 6.3 Final Commit
```bash
git add .
git commit -m "refactor(order): complete processOrder decomposition
- Extract validateOrder (20 lines)
- Extract calculateTotals (25 lines)
- Extract processPayment (30 lines)
- Extract sendConfirmation (20 lines)
- Main function now 25 lines (was 120)
No behavior changes. All tests passing."
```
---
## Refactoring Catalog
### Quick Reference
| Refactoring | When | Effort | Risk |
|-------------|------|--------|------|
| Rename | Unclear naming | Low | Low |
| Extract Method | Long function | Low | Low |
| Extract Variable | Complex expression | Low | Low |
| Inline | Over-abstraction | Low | Low |
| Extract Class | Large class | Medium | Medium |
| Move Method | Feature envy | Medium | Medium |
| Extract Parameter Object | Long param list | Medium | Low |
| Replace Conditional with Polymorphism | Complex switch | High | Medium |
| Replace Inheritance with Composition | Rigid hierarchy | High | High |
### IDE Support
Most refactorings have IDE shortcuts:
| Action | VS Code | JetBrains |
|--------|---------|-----------|
| Rename | F2 | Shift+F6 |
| Extract Method | Ctrl+Shift+R | Ctrl+Alt+M |
| Extract Variable | Ctrl+Shift+R | Ctrl+Alt+V |
| Move | Drag or F2 | F6 |
| Inline | N/A | Ctrl+Alt+N |
---
## Checklist
### Before Refactoring
- [ ] Clear goal defined
- [ ] Tests exist (>60% coverage)
- [ ] Impact analysis complete
- [ ] Step-by-step plan created
- [ ] Checkpoint committed
### During Refactoring
- [ ] One change at a time
- [ ] Tests run after each change
- [ ] Commit after each successful change
- [ ] No behavior changes introduced
### After Refactoring
- [ ] All tests pass
- [ ] Coverage maintained
- [ ] Code cleaner (measurable)
- [ ] Documentation updated
- [ ] Patterns documented (if applicable)
---
## Related Resources
- **Workflows**: code-review.md, testing-strategy.md, troubleshooting.md
- **Detailed Examples**: See `references/process.md` for code patterns
- **Refactoring Book**: Martin Fowler's "Refactoring: Improving the Design of Existing Code"
Files in this package (2)
- SKILL.md 11 KB
- references/process.md 21 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ar4mirez/samuel | 100 | MIT |
| gabrieldulolmarques/refactoring-skill | 100 | CC-BY-4.0 |
| 4typen/skills | 100 | MIT |
| t8jwscc7qy-sketch/foma-skills | 100 | Apache-2.0 |
| mtwuser/zero-cloud-gravity | 100 | MIT |
| krzysztofsurdy/code-virtuoso | 100 | MIT |
| sagargupta16/claude-skills | 100 | MIT |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
| DariuszDusza/agentic-workflow-foundry | 100 | Apache-2.0 |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 2849f0bf1e3d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100qe-refactoring-patterns
Apply safe refactoring patterns to improve code structure without changing behavior. Use when cleaning up code, reducing technical debt, or improving maintainability. - 84refactor
Systematic refactoring with behavior preservation. Use when improving existing code structure, reducing technical debt, or when code smells are detected. - 93code-quality
two-stage review (spec compliance first, then code quality), refactoring, and quality improvement. Use when reviewing code, eliminating code smells, reducing technical debt, refactoring methods, running self-critique loops, or improving maintainability and readability. - 100craftsman-refactor
Systematic refactoring with behavior preservation. Use when improving existing code structure, reducing technical debt, or when code smells are detected. - 100tech-debt
Scans the codebase for technical debt indicators, categorizes and prioritizes findings, and maintains a debt register with repayment recommendations. Use when assessing codebase health, planning refactoring, or when the user mentions technical debt or code quality. - 100code-refactoring-tech-debt
Technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Use when auditing a codebase for technical debt or planning remediation.