skills.rest
kieranpotts
kieranpottsCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

refactor

Restructure existing code to improve one design quality without changing observable behavior.

Updated Feb 12, 2026
Search Tags:#code quality#refactoring#clean code#technical debt#test coverage#coupling#cohesion
One-click install
npx skills add https://github.com/kieranpotts/skills --skill refactor-kieranpotts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactor
Source: https://github.com/kieranpotts/skills/tree/main/skills/refactor
Command: npx skills add https://github.com/kieranpotts/skills --skill refactor-kieranpotts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate structural drift over time, and manual refactoring often mixes behavior changes with restructuring, producing unreviewable diffs and broken tests. This Skill guides an agent through disciplined, test-guarded refactoring that improves one named design quality per session while keeping every commit green and independently revertible. ## Core Features & Use Cases - Single-quality focus: Improves exactly one named quality per session — readability, cohesion, coupling, naming, or decomposition — so diffs stay reviewable. - Small reversible moves: Works in atomic steps (rename one symbol, extract one function, inline one variable), each committed separately with passing tests. - Safety-net enforcement: Verifies test coverage before starting, adds characterization tests where coverage is thin, and never edits test files during the refactor. - Use Case: After an audit flags that OrderService mixes parsing, pricing, and persistence, invoke the skill to split it into three cohesive modules across three green commits, with no test file touched. ## Quick Start Ask the agent to refactor this module for readability without changing any behavior.

Frequently Asked Questions about refactor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor code without changing its behavior?▼

Refactor in small reversible moves such as renaming one symbol or extracting one function, running the covering tests after each move and committing only when green. Each commit holds exactly one move so any step can be reverted independently.

How to safely refactor legacy code with poor test coverage?▼

Add characterization tests first that pin down current behavior, committed as a separate maintenance change before any refactoring. If you cannot quickly build that safety net, do not refactor, because behavior preservation cannot be verified.

Can I combine a refactor with a bug fix in the same commit?▼

No. Bundling a fix with restructuring makes it impossible to tell what changed behavior and removes the ability to roll back one move. Commit the green refactoring moves, then report the bug as a separate task.

When should I not use automated refactoring on a codebase?▼

Avoid it on code with no tests and no quick way to add characterization tests, and when a move would redraw module boundaries, change a public interface, or alter the data model. Those are design changes that belong in a design process first.

Why should a refactoring session improve only one quality at a time?▼

Improving cohesion, naming, and simplicity in one pass produces a diff nobody can review and loses selective rollback. Pick one named quality per session and schedule the rest as follow-up refactors.

Related Skills

Explore More Software Engineering Skills→
IntegralistIntegralist
2

redesign

Audit codebases for complexity, standards drift, and test coverage gaps.

Community
Advanced
kanade0404kanade0404

tidy-first

Separate structural cleanup from behavioral code changes in commits.

Community
Advanced
simotasimota
68

Atlas

Analyzes software architecture by mapping module dependencies and detecting structural risks.

Community
Advanced
juspayjuspay

lowy

Identify module boundaries that separate sequence and activity volatility.

Official
Advanced