Agent skill · personamanagmentlayer
refactoring-workflow
Improve the structure of existing code without changing its behaviour, in small verified steps under a green test suite. Use when the user asks to refactor, clean up, restructure or simplify code, wants to reduce duplication or coupling, is preparing a codebase for a feature it cannot currently accommodate, or when the task involves extracting functions, splitting modules, breaking dependencies, or paying down technical debt.
What it needs
About 6k tokens when loaded.
What this skill does
Refactoring Workflow Refactoring is changing the structure of code without changing its behaviour. If behaviour changes, it is not a refactor — it is a rewrite, and it needs a different plan and a different review. When to Use This Skill The user asks to refactor, clean up, restructure or simplify A feature is hard to add because the current structure resists it Duplication has reached the point where a change must be made in several places A module has grown beyond what one reader can hold in mind Coupling makes a unit impossible to test in isolation Do not refactor when the tests are red, when you do not understand the current behaviour, or as a side quest inside a feature branch. Refactoring merged together with behaviour change is unreviewable. Core Concepts The Two Hats You are either adding behaviour or restructuring — never both in the same edit. Kent Beck's metaphor: swap hats deliberately, and know which one you are wearing. When a refactor reveals a bug, note it and finish the refactor; fix the bug in a separate change with its own test. The Precondition A refactor is safe only to the extent that behaviour is observable. That means a green test suite covering the paths you will touch. Without it you are not refactoring, you are editing and hoping. If coverage is missing, stop and add characterisation tests first — see the tdd-workflow skill, which covers seams and characterisation in depth. Small Steps Each step should be small enough that you can name what it did and revert it alone. Run the suite after every step. Two hours of unverified restructuring followed by a red suite gives you no information about which edit broke it. Make the Change Easy, Then Make the Easy Change When a feature is hard to add, do not force it into the existing shape. First refactor until the feature becomes a small addition, then add it. These are two commits, in that order. The Workflow 1. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills personamanagmentlayer/refactoring-workflow