refactor

Refactor

Improve code structure and readability without changing external behavior. Behavior is sacred; structure is up for negotiation.

Core Principle

Discover before you fix. It's tempting to jump straight into the most obvious problem, but surveying the whole file first gives a better picture of what's worth fixing and in what order. It also surfaces smell dependencies (fixing X may make Y irrelevant). Never start editing until you've cataloged.

Phase 0 — Discover

Read the target file(s). Note language. Scan for every smell present.

Language detection: Adapt patterns and tool suggestions to the actual language:

Language	Smell finders	Refactor tools
TS / JS	ESLint, ts-prune, unimported	ts-morph, jscodeshift, ast-grep
Python	pylint, ruff, vulture	rope, pyupgrade, ruff --fix
Go	staticcheck, golangci-lint	gorename, gopls
Rust	clippy	cargo fix

Also read 2–3 similar files in the project before proposing changes. Refactoring should feel native to the codebase — matching its naming conventions, its error-handling style, its test structure. A brilliant refactor that looks foreign is still a bad refactor.

Catalog your findings:

Smells found in auth.ts:
  [HIGH]  Nested conditionals — handleAuth() has 8 levels of nesting; every error path buried inside
  [HIGH]  Long method — 120 lines doing token parse, DB lookup, audit log, and response all in one
  [MED]   Magic numbers — status === 2 and status === 1 appear without named constants
  [LOW]   Feature envy — Order.calculateDiscount() reads deep into User internals

Surface the catalog in this format — include all four parts:

Smells found in <filename>:
  [HIGH] ...
  [MED]  ...
  [LOW]  ...

Tool that catches this automatically: <name> (e.g. ESLint no-unused-vars, pylint, ruff, ts-prune)

Behavior guarantee: All changes will preserve external behavior — same inputs, same outputs, same side effects.

Scope: I'll fix [highest-priority smell / the one you mentioned]. Which smells should I address this session?