77 lines
3.1 KiB
Markdown
77 lines
3.1 KiB
Markdown
---
|
|
description: Refactor workflow for safely restructuring existing code
|
|
---
|
|
|
|
# Refactor Workflow
|
|
|
|
## Purpose
|
|
Safely restructure existing code while preserving behavior. Uses a different mindset than greenfield feature development: understand first, then change structure.
|
|
|
|
## When to Use
|
|
- Code restructuring (moving, renaming, splitting modules)
|
|
- Pattern migration (e.g., switching from callbacks to async/await)
|
|
- Dependency upgrades with breaking changes
|
|
- Addressing tech debt or architectural improvements
|
|
|
|
**Requires a specific goal.** Invoke with a clear target, not an open directory:
|
|
- ✅ `/refactor extract storage interface in task feature`
|
|
- ✅ `/refactor split user handler into separate auth handler`
|
|
- ❌ `/refactor apps/backend` (too vague — use `/audit` first to find specific issues)
|
|
|
|
## When NOT to Use
|
|
- New features (use `/orchestrator`)
|
|
- Small bug fixes (use `/quick-fix`)
|
|
- "Find what to improve" (use `/audit` first, then `/refactor` for structural findings)
|
|
|
|
## Pre-Implementation Checklist
|
|
Before starting, you MUST:
|
|
1. Scan `.agents/rules/` directory for applicable rules
|
|
2. Read `architectural-pattern.md` and `project-structure.md`
|
|
3. Read `rule-priority.md` for conflict resolution
|
|
|
|
## Phases
|
|
|
|
### Phase 1: Impact Analysis
|
|
**Set Mode:** Use `task_boundary` to set mode to **PLANNING**
|
|
|
|
1. **Map the blast radius** — what files, modules, and tests are affected?
|
|
2. **Document existing behavior** — what tests currently pass? what contracts exist?
|
|
3. **Identify risks** — can this be done incrementally or is a big-bang needed?
|
|
4. **Create refactoring plan** in `task.md` with incremental steps
|
|
5. If decision involves trade-offs, create an ADR using the **ADR Skill**
|
|
|
|
**Skills to consider:**
|
|
- **Sequential Thinking** — for multi-step refactoring with interdependencies
|
|
|
|
### Phase 2: Incremental Change (TDD)
|
|
**Set Mode:** Use `task_boundary` to set mode to **EXECUTION**
|
|
|
|
For each step in the refactoring plan:
|
|
1. **Ensure existing tests pass** before making any change
|
|
2. **Make one incremental change** — move, rename, or restructure
|
|
3. **Run tests after each change** — behavior must be preserved
|
|
4. **Add new tests** if the refactoring exposes untested behavior
|
|
5. Follow applicable rules:
|
|
- Architectural Patterns @architectural-pattern.md
|
|
- Code Organization Principles @code-organization-principles.md (includes circular dependency guidance)
|
|
|
|
**Key principle:** Never break the build for more than one step at a time.
|
|
|
|
### Phase 3: Parity Verification
|
|
**Set Mode:** Use `task_boundary` to set mode to **VERIFICATION**
|
|
|
|
1. Run the full validation suite (same as `/4-verify`)
|
|
2. **Compare test coverage** — coverage should be equal to or better than before
|
|
3. **Verify no behavior changes** — same inputs produce same outputs
|
|
4. If applicable, run E2E tests (`/e2e-test`)
|
|
|
|
### Phase 4: Ship
|
|
Follow `/5-commit` with commit type `refactor(<scope>): <description>`
|
|
|
|
## Completion Criteria
|
|
- [ ] Impact analysis documented
|
|
- [ ] All changes made incrementally with tests passing at each step
|
|
- [ ] Full verification suite passes
|
|
- [ ] Test coverage is equal to or better than before
|
|
- [ ] Committed with `refactor` type
|