Refactoring Skill
Core Philosophy
"Behavior stays the same; structure improves."
Change structure and names, not observable behavior. Small steps, with tests (or quick verification) after each step.
Protocol
1. Establish Safety
- Tests: If tests exist, ensure they pass before and after. Add minimal tests for critical behavior if missing.
- Scope: Refactor one concern at a time (e.g. one function, one type, one file). Avoid mixing refactor with new features or bug fixes in the same commit when possible.
2. Common Operations
| Operation |
Approach |
| Extract function/method |
Identify cohesive block, extract, name by intent, replace call site(s). |
| Rename |
Use IDE rename (symbol/identifier) so all references update; verify tests. |
| Move |
Move to the right module/class; update imports and references. |
| Simplify conditionals |
Guard clauses, early returns, replace nested conditionals with clear branches or lookup. |
| Remove duplication |
Extract shared logic; parameterize or abstract; avoid over-abstracting too early. |
| Split large function/file |
Extract by responsibility; keep public surface clear. |
3. Order of Work
- Understand current behavior (and tests).
- Pick one refactor; do it; run tests (or smoke-check).
- Commit or stage; repeat.
- If tests are missing and refactor is risky, add a minimal test first, then refactor.
4. Commands
- Run tests after changes:
npm test, pytest, go test ./..., etc., per project.
- Search for references before rename/move:
grep or IDE "Find references".
5. When NOT to Refactor
- Low-traffic, stable code - If no one touches it and it works, leave it alone.
- Before understanding - Don't refactor code you don't fully understand yet; read and test first.
- Mixed with features/fixes - Don't combine refactoring with behavior changes in the same commit.
- Without tests - If there are no tests and you can't quickly add them, the risk of silent breakage is high.
- Under time pressure - Refactoring under deadline pressure leads to half-done changes that are worse than the original.
6. Large-Scale Refactoring
For refactors spanning multiple files or modules:
- Map the scope - Identify all affected files, imports, and call sites before starting.
- Plan the sequence - Order changes to minimize broken intermediate states (e.g., introduce new interface first, then migrate callers, then remove old code).
- Feature branch - Always use a dedicated branch for large refactors.
- Incremental commits - One logical change per commit; each commit should leave tests passing.
- Parallel safety - If using parallel subagents (RLM skill), ensure changes don't conflict across files.
7. Performance Implications
- Measure before and after if refactoring hot paths (use the performance skill for profiling).
- Extra abstractions add indirection — acceptable for clarity but watch for overhead in tight loops.
- Data structure changes (e.g., array → map) can affect performance positively or negatively; benchmark if critical.
8. Cross-Skill Integration
| Situation |
Skill to invoke |
| Need tests before refactoring |
testing skill |
| Refactoring reveals a security issue |
security-reviewer skill |
| Refactoring changes API surface |
code-reviewer skill |
| Refactoring affects performance-critical code |
performance skill |
Checklist
1---2name: refactoring3description: Refactor code safely: extract, rename, simplify, and reorganize without changing behavior. Use when the user asks to refactor, extract function, rename, simplify, or clean up this code.4---56# Refactoring Skill78## Core Philosophy910**"Behavior stays the same; structure improves."**1112Change structure and names, not observable behavior. Small steps, with tests (or quick verification) after each step.1314---1516## Protocol1718### 1. Establish Safety1920- **Tests**: If tests exist, ensure they pass before and after. Add minimal tests for critical behavior if missing.21- **Scope**: Refactor one concern at a time (e.g. one function, one type, one file). Avoid mixing refactor with new features or bug fixes in the same commit when possible.2223### 2. Common Operations2425| Operation | Approach |26| ----------------------------- | ---------------------------------------------------------------------------------------- |27| **Extract function/method** | Identify cohesive block, extract, name by intent, replace call site(s). |28| **Rename** | Use IDE rename (symbol/identifier) so all references update; verify tests. |29| **Move** | Move to the right module/class; update imports and references. |30| **Simplify conditionals** | Guard clauses, early returns, replace nested conditionals with clear branches or lookup. |31| **Remove duplication** | Extract shared logic; parameterize or abstract; avoid over-abstracting too early. |32| **Split large function/file** | Extract by responsibility; keep public surface clear. |3334### 3. Order of Work35361. Understand current behavior (and tests).372. Pick one refactor; do it; run tests (or smoke-check).383. Commit or stage; repeat.394. If tests are missing and refactor is risky, add a minimal test first, then refactor.4041### 4. Commands4243- Run tests after changes: `npm test`, `pytest`, `go test ./...`, etc., per project.44- Search for references before rename/move: `grep` or IDE "Find references".4546### 5. When NOT to Refactor4748- **Low-traffic, stable code** - If no one touches it and it works, leave it alone.49- **Before understanding** - Don't refactor code you don't fully understand yet; read and test first.50- **Mixed with features/fixes** - Don't combine refactoring with behavior changes in the same commit.51- **Without tests** - If there are no tests and you can't quickly add them, the risk of silent breakage is high.52- **Under time pressure** - Refactoring under deadline pressure leads to half-done changes that are worse than the original.5354### 6. Large-Scale Refactoring5556For refactors spanning multiple files or modules:57581. **Map the scope** - Identify all affected files, imports, and call sites before starting.592. **Plan the sequence** - Order changes to minimize broken intermediate states (e.g., introduce new interface first, then migrate callers, then remove old code).603. **Feature branch** - Always use a dedicated branch for large refactors.614. **Incremental commits** - One logical change per commit; each commit should leave tests passing.625. **Parallel safety** - If using parallel subagents (RLM skill), ensure changes don't conflict across files.6364### 7. Performance Implications6566- **Measure before and after** if refactoring hot paths (use the **performance** skill for profiling).67- **Extra abstractions** add indirection — acceptable for clarity but watch for overhead in tight loops.68- **Data structure changes** (e.g., array → map) can affect performance positively or negatively; benchmark if critical.6970### 8. Cross-Skill Integration7172| Situation | Skill to invoke |73|-----------|----------------|74| Need tests before refactoring | **testing** skill |75| Refactoring reveals a security issue | **security-reviewer** skill |76| Refactoring changes API surface | **code-reviewer** skill |77| Refactoring affects performance-critical code | **performance** skill |7879---8081## Checklist8283- [ ] No intentional behavior change; only structure and names.84- [ ] Tests pass (or equivalent verification) after each logical step.85- [ ] Renames and moves are consistent (all references updated).86- [ ] Commits are focused (one refactor type or one area per commit when practical).87- [ ] Large-scale refactors have a clear plan and incremental commits.88- [ ] Performance-sensitive code benchmarked before and after (if applicable).
micaelmalta