/refactor — Code Quality Pass
Overview
Improve code structure without changing behavior. Propose changes, get approval, make one change at a time with tests between each.
Core principle: Never change behavior. Tests must stay green after every change.
When to Use
-
After implementation and QA pass
-
User requests a quality check on recent work
-
You notice structural issues while working
The Process
- Establish Baseline
Run the test suite first. Actually run it.
~/bin/eldev etest -r dot
Record the result. This is your safety net. If tests aren't green before you start, fix that first.
- Identify What Changed
git diff main...HEAD # if on a branch git log --oneline -N # user specifies range
Read all changed files in full — not just the diff. Context matters.
- Find Issues
Look for:
Issue Signal
DRY violations Same logic in two places
SRP violations Function hard to name (doing too much)
Naming Names don't match what the code does
Unnecessary complexity Abstraction not earning its keep
Dead code Unreachable branches, unused functions
Don't look for:
-
Style preferences (tab vs space, quote style)
-
Missing documentation on unchanged code
-
"Improvements" to code you didn't change
- Propose Changes — Get Approval
Present refactorings ordered by highest impact, lowest risk first:
1. [Title] — Impact: High, Risk: Low
What: [what to change] Why: [why it improves the code] Risk: [what could go wrong]
Ask the user which to do. Don't start changing code without approval.
- Make Changes — One at a Time
For each approved refactoring:
-
Run tests — confirm green before starting
-
Make one change — a single, atomic refactoring
-
Run tests — confirm still green
-
Commit — describe the refactoring, not the code
If tests fail after a change: revert immediately. You introduced a bug.
- Final Verification
~/bin/eldev etest -r dot
All tests must pass. Report the final state.
Common Mistakes
Mistake Fix
Changing behavior ("while I'm here") Refactoring changes structure ONLY. If tests break, revert.
Not running tests before starting Run tests FIRST. No green baseline = no refactoring.
Making changes without user approval Propose, get approval, then act.
Multiple changes at once One change, one test run, one commit. Atomic.
Renaming public API That's a breaking change, not a refactoring.
Proposing 10+ changes Focus on 3-5 highest-impact items. Less is more.
Describing changes without making them Actually edit the files. Actually run the tests.