Detect code smells and apply *in-place* refactoring techniques (Extract Method/Class, Replace Conditional, Introduce Parameter Object, Rename, Move) to improve clarity, testability, and maintainability of a single function, class, or file.
TRIGGER when: user mentions refactoring opportunities, code smell, long method, large class, primitive obsession, long parameter list, data clumps, feature envy, shotgun surgery, switch statement smell, extract method, extract class, replace conditional with polymorphism, introduce parameter object, simplify single file, improve readability, tidying, tidy first, "clean up this function", "refactor this class".
DO NOT USE when: no tests exist (unsafe to refactor blind — add tests first), the change is behavior-altering rather than structure-only (use `tcrdd` instead), or the user needs to safely untangle a *cross-file* dependency graph where one change ripples to many call sites (use `mikado-method` instead).
Detect code smells and apply *in-place* refactoring techniques (Extract Method/Class, Replace Conditional, Introduce Parameter Object, Rename, Move) to improve clarity, testability, and maintainability of a single function, class, or file.
TRIGGER when: user mentions refactoring opportunities, code smell, long method, large class, primitive obsession, long parameter list, data clumps, feature envy, shotgun surgery, switch statement smell, extract method, extract class, replace conditional with polymorphism, introduce parameter object, simplify single file, improve readability, tidying, tidy first, "clean up this function", "refactor this class".
DO NOT USE when: no tests exist (unsafe to refactor blind — add tests first), the change is behavior-altering rather than structure-only (use `tcrdd` instead), or the user needs to safely untangle a *cross-file* dependency graph where one change ripples to many call sites (use `mikado-method` instead).
Refactoring: Smells & Techniques
A comprehensive guide to detecting code smells and applying refactoring techniques to improve design, clarity, and maintainability.
Read On Demand
Read When
File
Identifying code smells or reviewing a diff/PR for bloaters
Never auto-remove TODO comments. TODOs require manual human decision — surface them, don't delete them.
Rule of Three before extracting. Wait for the third duplication before Extract Method / Extract Class. Two points don't reliably reveal the right abstraction.
No tests, no refactor. Don't refactor blind — add a safety net first.
Pair comment tidyings. When deleting redundant comments, also scan for missing why comments worth adding.
Smells → Techniques (Quick Reference)
Smell
Detection Signal
Technique(s)
Long Method
>10 lines, multiple responsibilities
Extract Method (Rule of Three)
Large Class
>10 methods, multiple concerns, hard to test
Extract Class (Rule of Three)
Primitive Obsession
String/int constants for domain concepts
Create Type/Object
Long Parameter List
>3-4 parameters, related params
Introduce Parameter Object
Data Clumps
Same variables in multiple places
Extract Class
Comments
Code needs a comment to be understood (see smells.md for subtypes)
