| name | refactor |
| description | Improve code structure without changing behavior, verifying with tests at every step. Use this when you want to restructure, extract, rename, or simplify existing code that already works. |
| user-invocable | true |
Safe Refactoring
Improve code structure without changing behavior. Every step verified by tests, with quality gates passing before and after each change.
Auto Mode
When ## Auto Mode Active is present in context: do not pause for confirmation. Plan the steps using reasonable defaults, surface the plan and assumptions inline, then execute step by step with per-step quality gates. When the refactor's scope or target is genuinely ambiguous — what to restructure into what — ask, following the shared recommendation convention (godmode:recommend-convention) in rules/godmode-recommend.md: lead with your best-inferred answer to override, not a blank prompt (e.g. "I'll extract X into Y unless you'd scope the boundary differently"), then let the user redirect. Treat user course-corrections as normal input.
The Job
- Verify baseline
- Plan steps
- Execute one step at a time with test verification
- Report results
Process
1. BASELINE
- Run ALL quality gates (from
config/quality-gates.txt). They must pass.
- If not: fix quality issues first (separate commit).
- Note current test count and coverage.
2. IDENTIFY
- What specifically needs improving and WHY
- Is this refactoring or a behavior change? (If behavior → wrong skill, use normal workflow)
- Scope: list exactly which files/functions are affected
3. PLAN
- Break into steps, each independently committable
- Order: safest/simplest first, riskiest last
- Each step leaves the code in a working state
4. EXECUTE (repeat per step)
a. Apply one refactoring
b. Run quality gates
c. If GREEN → commit: "refactor: [what was done]"
d. If RED → revert immediately, try smaller step
5. VERIFY
- Run full quality gates
- Compare test count (same or higher, never lower)
- Compare coverage (same or higher)
- Confirm: no behavior changed
Common Refactorings
| Refactoring | When to use |
|---|
| Extract function | >40 lines, mixed responsibilities |
| Rename | Name doesn't describe purpose |
| Inline | Abstraction adds complexity without value |
| Move | Code in wrong module/file |
| Split file | >300 lines or mixed responsibilities |
| Simplify conditional | Nested if/else, complex booleans |
| Replace magic values | Hardcoded numbers/strings |
| Improve types | any, loose types where precise ones exist |
Rules (Non-Negotiable)
- NEVER mix refactoring with feature changes in the same commit
- Quality gates must pass before AND after EACH step
- If gates break: REVERT. Don't fix forward during refactoring.
- Commit after each successful step
- When
.planning/STANDARDS.md is present, the code you restructure must honor it as authoritative project context over the generic defaults where it has spoken (see "Project Standards Precedence" in rules/godmode-coding.md)
Agent Routing
| Step | Agent | Purpose |
|---|
| IDENTIFY | MUST spawn @researcher | Explore affected files, find all callers/consumers, map dependencies before planning |
| PLAN | Always spawn @architect when >5 files affected | Validate refactoring approach and step ordering for large-scope changes |
| VERIFY | MUST run /verify (5 parallel review lenses) | Review each completed refactoring step for correctness and regressions |
Rule: Never explore the codebase inline when @researcher can do it in parallel.
Feeding Back Into the Workflow
After the PLAN step, decide how the refactoring re-enters the workflow spine:
- Execute now (default). Apply all steps immediately with per-step test verification and an atomic commit per step. Best for small refactorings (1-2 steps).
- Defer as a work unit. When the refactoring is large (3+ steps) and deserves its own planning pass, append a work unit to
.planning/missions/<mission_id>/ROADMAP.md describing the area and the planned steps, then pick it up with /brief N. The brief captures the why + what, /plan N re-derives the steps, and /build N executes them with the same per-step verification.
In Auto Mode, execute now for small refactorings; for large ones, append a work unit and say so inline.
Appended work-unit note (for .planning/missions/<mission_id>/ROADMAP.md):
- Refactor: [area] — N steps, structure only, no behavior change.
Steps: [short list]. Quality gates must pass before AND after each step.
Output
Refactoring: [what and why]
Steps completed: N
1. [step] — gates pass ✓
2. [step] — gates pass ✓
Tests: [before] → [after]
Coverage: [before] → [after]
Related
- /tdd — for TDD-style development of new features
- /debug — if refactoring reveals bugs, switch to debug protocol
- /verify — runs the 5 parallel review lenses on refactoring changes before committing
Spine: plan the steps, then either execute now (/ship) or append a work unit to .planning/missions/<mission_id>/ROADMAP.md and resume the spine at /brief N.
