# Refactoring

> Safely restructure code without changing behavior using Extract Method, Rename, Move Method techniques. Use when preparing code for new features, improving code quality incrementally, cleaning up messy code, reducing duplication, or simplifying complex logic. Make sure to use this skill whenever the user mentions refactoring, cleaning up code, making code more readable, splitting large files or m…

- **Type:** Skill
- **Install:** `agentstack add skill-elct9620-ai-coding-skills-refactoring`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [elct9620](https://agentstack.voostack.com/s/elct9620)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [elct9620](https://github.com/elct9620)
- **Source:** https://github.com/elct9620/ai-coding-skills/tree/main/skills/refactoring

## Install

```sh
agentstack add skill-elct9620-ai-coding-skills-refactoring
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Related Skills

- Facing a design trade-off (DRY vs KISS)? → Use **principles** first to decide, then refactor
- Code is in the wrong architectural layer? → Use **architecture** to identify target, then refactor to move it
- Need to choose a pattern (Strategy, Factory)? → Use **design-patterns** first, then refactor toward it
- No tests before refactoring? → Use **testing** to add them first

## Applicability Rubric

| Condition | Pass | Fail |
|-----------|------|------|
| Existing code modification | Need to change existing code | Writing new code only |
| Code comprehension issues | Code hard to understand/extend | Code is clear |
| Feature preparation | Preparing for new functionality | Direct implementation possible |
| Incremental improvement | Improving quality step by step | No improvement needed |

**Apply when**: Any condition passes

## Core Principles

### The Refactoring Cycle

```
1. Ensure tests exist (or add them)
   ↓
2. Make small change
   ↓
3. Run tests
   ↓
4. Commit if green
   ↓
5. Repeat
```

### Golden Rules

- **Never refactor and change behavior simultaneously**
- **Always have tests before refactoring**
- **Small steps, frequent commits**
- **If tests fail, revert immediately**
- **Never rewrite from scratch** — a big-bang rewrite throws away years of bug fixes and domain knowledge. Instead, extract one piece at a time, test it, and ship it. If your refactoring plan requires "stop the world and replace everything," the plan is wrong — break it into smaller incremental steps.

### Preserve the Semantic Contract, Not Just the Signature

Behavior is more than the type signature. A change that leaves names and types untouched can still alter what a return value promises, when effects become observable, or how failures are reported. If callers would need to reason differently about the function after the change, it is a behavior change rather than a refactor, even when the compiler is satisfied.

The semantic contract includes at least:

- Meaning of return values and out-parameters — what a given value promises happened.
- Completion timing — whether effects are visible by the time the call returns (sync vs. deferred/async).
- Observable side effects at return — which external state has been committed before returning.
- Error model — how failure is surfaced (exception, false, partial result, retried later).
- Ordering, atomicity, and delivery guarantees — all-or-nothing vs. partial, exactly-once vs. at-least-once, and similar.

If any of these shift, update the contract explicitly (rename, change return type, document the new guarantee, migrate callers) rather than hiding the change inside a refactor.

## Common Refactoring Techniques

### Code Organization

| Technique | When to Use | Before → After |
|-----------|-------------|----------------|
| Extract Method | Long method, repeated code | Inline code → Named method |
| Extract Class | Class has multiple responsibilities | One class → Two classes |
| Move Method | Method uses another class more | A.method() → B.method() |
| Rename | Name doesn't reveal intent | `d` → `elapsedDays` |

### Simplification

| Technique | When to Use | Before → After |
|-----------|-------------|----------------|
| Replace Conditional with Polymorphism | Type-based switching | if/switch → Subclasses |
| Replace Magic Number | Unexplained literals | `86400` → `SECONDS_PER_DAY` |
| Remove Dead Code | Unused code | Code → Nothing |
| Simplify Conditional | Complex boolean logic | Nested ifs → Guard clauses |

### Dealing with Dependencies

| Technique | When to Use | Before → After |
|-----------|-------------|----------------|
| Extract Interface | Need to mock or swap | Concrete → Interface + Concrete |
| Inject Dependency | Hard-coded dependency | `new Dep()` → Constructor param |
| Replace Inheritance with Delegation | Inheritance misused | extends → has-a |

## Safe Refactoring Steps

### Extract Method

1. Identify code to extract
2. Create new method with descriptive name
3. Copy code to new method
4. Replace original code with method call
5. Run tests
6. Commit

### Rename

1. Find all usages
2. Rename (use IDE refactoring if available)
3. Remove comments the new name has made redundant
4. Run tests
5. Commit

### Move Method

1. Copy method to target class
2. Adjust for new context
3. Update original to delegate
4. Run tests
5. Remove original method
6. Run tests
7. Commit

## Completion Rubric

### Before Refactoring

| Criterion | Pass | Fail |
|-----------|------|------|
| Test coverage | Tests exist and pass | No tests or failing tests |
| Behavior understanding | Current behavior understood | Unclear behavior |
| Clear goal | Refactoring goal defined | No clear objective |
| Team awareness | Team knows the scope | Undisclosed changes |

### During Refactoring

| Criterion | Pass | Fail |
|-----------|------|------|
| Single focus | One refactoring at a time | Multiple simultaneous changes |
| Test validation | Tests run after each change | No test verification |
| Incremental commits | Commit after each step | Large uncommitted changes |
| Behavior preservation | Return-value meaning, completion timing, side-effect ordering, and error model all unchanged | Semantic contract shifted even though the signature stayed the same |

### After Refactoring

| Criterion | Pass | Fail |
|-----------|------|------|
| Tests passing | All tests still pass | Tests failing |
| Code clarity | Code is cleaner/clearer | Same or worse clarity |
| No new features | No functionality added | Features added |
| Review completed | Changes reviewed | No review |

## Code Smells to Watch For

| Smell | Signal | Refactoring |
|-------|--------|-------------|
| Long Method | Hard to describe in one sentence | Extract Method |
| Large Class | Multiple unrelated responsibilities | Extract Class |
| Long Parameter List | Parameters that always travel together | Introduce Parameter Object |
| Duplicated Code | Same logic in multiple places | Extract Method/Class |
| Feature Envy | Method uses another class's data more than its own | Move Method |
| Data Clumps | Same data groups appear together | Extract Class |
| Explanatory Comment | Comment restates the code in prose | Extract Method with an intent-revealing name |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [elct9620](https://github.com/elct9620)
- **Source:** [elct9620/ai-coding-skills](https://github.com/elct9620/ai-coding-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-elct9620-ai-coding-skills-refactoring
- Seller: https://agentstack.voostack.com/s/elct9620
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.