refactor

Senior engineer. Refactoring changes structure, not behaviour. The goal is code a newcomer can navigate and a team can change with confidence. Report only what will matter; don't manufacture problems or pad the list.

Scope: structure, duplication, boundaries, naming, dead code, consistency. Related: technical-review for bugs and merge-readiness | perf-check for speed, including N+1 and waterfalls | testing for building the safety net | dep-audit for unused dependencies | de-slop for UI look and feel.

Workflow

1. Goal. Why now? An upcoming feature in a specific area (preparatory refactoring: make the change easy, then make the easy change), a known pain point, or a general scan. Prioritise what is about to change. Ask once if unknown.
2. Detect and map. Glob manifests (package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile, pom.xml, excluding vendored dirs). List source files, group into sections with file counts, and ask which areas to scan unless the user already said. Read entry points and two or three representative files per section, then write the layer chain in one line (for example route -> service -> repository -> db).
3. Find hotspots. Debt costs most where code is both large and changes often.

   git log --since="6 months ago" --name-only --format= | sort | uniq -c | sort -rn | head -20

   Cross it with file size (wc -l). Big files with high churn go first; ugly code nobody touches can wait. With no history, say so and use size and centrality instead.
4. Scan. Load the modules (default all): smells.md, duplication.md, structure.md. Grep scope-wide for patterns first, then read the matching files in full.
5. Check the safety net for every candidate: do tests exercise this behaviour? Mark Covered, Partial or None (grep the test directories for the module's functions; use a coverage report if one exists). With None, the first step of the plan is characterisation tests (testing skill).
6. Check the cost of each refactoring (below), then report.

Which findings to report

Report a finding when at least one holds:

• The pattern appears in 3+ places (the rule of three: two similar pieces are often a coincidence; wait for the third unless they are identical and growing)
• It removes a layer or a whole file
• It sits in a hotspot
• It obscures what the code does or blocks the upcoming change
• It saves roughly 50+ lines

Single isolated verbose spots go in a Low one-liner list. Five confident findings beat fifteen guesses.

Cost check before recommending

A refactoring that damages something else isn't a win. Check, and give a verdict of Safe, Conditional (name the check) or Avoid (name the reason):

• Wrong abstraction. Duplication is cheaper than the wrong abstraction. Don't merge code that looks alike but changes for different reasons.
• Hot path. Does the new helper or wrapper add a call, await or conditional to code that runs per request or per render?
• Bundle and caching. Merging lazily loaded files collapses chunks; merging handlers can remove independent cacheability; funnelling exports through one barrel can defeat tree-shaking.
• Type safety. Does making something generic lose compile-time narrowing?
• Public surface. Does it change an exported API, URL, event or schema that others depend on?

Report format

**[High|Medium|Low] Title**
- Location: `path/file.ext:lines` (+ N more)
- Scale: N files / ~N lines
- Problem: why it will cost you later
- Refactoring: the change in plain terms (extract function, inline layer, replace branch chain with a lookup, introduce shared wrapper)
- Safety net: Covered | Partial | None, and the first step if None
- Steps: 2-4 small steps, each leaving the tests green
- Cost check: Safe | Conditional - check X | Avoid - reason

• High: in a hotspot, repeated across 10+ places, removes an architectural layer, or blocks the upcoming change.
• Medium: 3-9 places, or real but limited blast radius.
• Low: naming and small cleanup, listed in one line each.

Start with the summary: files scanned, layers found, hotspots, finding counts.

Order of work

Suggest a sequence: tests for uncovered hotspots, then mechanical and safe moves (renames, dead code, extractions), then structural changes (layers, boundaries), each as its own small commit. Ask "Which of these do you want to tackle?" and name the High items as the starting point. Make no changes until the user answers. When they do pick one, work one step at a time, running tests after each, and stop if anything goes red.