trevoke /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
1. 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.
2. 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.
3. 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
4. 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.
5. 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.
6. 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. |