Code Refactoring

Diagnose structural problems in code using three lenses: pain (what hurts now), intent (what the code needs to become), and comprehension (what's hard to understand). Apply the smallest change that solves the real problem. Language-agnostic.

When to Use

• User shows code and asks "what's wrong with this?" or "how can I improve this?"
• User describes pain: brittle tests, cascading changes, files that grow endlessly
• User mentions smells by name or informal equivalents ("spaghetti code," "this does too much")
• User wants to apply a specific design pattern or refactoring technique
• User asks why code is hard to change, test, or understand
• User has a structural goal or upcoming need: "make this pluggable," "I need to add N more X," "we need to deploy these independently," "I want to support undo/redo"
• User struggles to understand code: "I can never remember how X works," "new devs take weeks," "the code works but I can't explain it," "what does this even do"

Don't use when: Code is a prototype/spike, about to be replaced, or the user just wants a feature added (refactor only if it enables the feature).