| name | refactor-plan |
| description | Creates detailed refactor plan with tiny commits via interview, files as GitHub RFC. Triggers: refactor plan, refactoring RFC, incremental refactor, safe steps. |
| user-invocable | true |
| effort | high |
| argument-hint | [area or module to refactor] |
| allowed-tools | Read, Grep, Glob, Bash, Agent |
Refactor Plan
$ARGUMENTS
Create a detailed refactor plan with tiny commits via user interview, filed as a GitHub issue.
Usage
/refactor-plan [area or module to refactor]
What This Command Does
- Gathers detailed problem description from user
- Explores the codebase to verify assertions
- Presents alternative approaches (>=3 options)
- Interviews about implementation details
- Checks test coverage of affected area
- Breaks into tiny commits (Martin Fowler: each step keeps codebase working)
- Files as GitHub issue via
gh issue create
Process
1. Gather Problem
Ask for detailed description of:
- The problem they want to solve
- Potential ideas for solutions
2. Explore Codebase
Use Agent (subagent_type=Explore) to verify assertions and understand current state.
3. Present Alternatives
Present >=3 alternative approaches. Discuss trade-offs.
4. Interview
Detailed interview about chosen approach. Hammer out exact scope — what changes, what doesn't.
5. Check Test Coverage
Explore existing test coverage for the affected area. If insufficient, ask about testing plans.
6. Break into Tiny Commits
Each commit:
- Leaves the codebase in a working state
- Is the smallest possible step
- Can be reviewed independently
7. File GitHub Issue
Use gh issue create with template below. Share URL immediately.
Issue Template
Problem Statement
The problem from the developer's perspective.
Solution
The solution from the developer's perspective.
Commits
Detailed plan in plain English, broken into the tiniest commits possible. Each commit leaves the codebase working.
Decision Document
Implementation decisions made:
- Modules to build/modify
- Interface changes
- Architectural decisions
- Schema changes
- API contracts
Do NOT include file paths or code snippets — they go stale.
Testing Decisions
- What makes a good test (external behavior, not implementation details)
- Which modules to test
- Prior art for tests in the codebase
Out of Scope
What is explicitly NOT part of this refactor.
Rules
- MUST present >=3 alternative approaches with trade-offs before committing to one
- MUST break the refactor into commits small enough to roll back individually — a commit that cannot be reverted is not tiny
- MUST verify test coverage of the affected area before planning; insufficient coverage is a blocker, not a warning
- NEVER embed file paths, code snippets, or function names in the issue body — the plan outlives the code
- NEVER ask for review after creating the issue — file it immediately, share the URL, iterate in comments
- CRITICAL: dead-code cleanup is per step, not deferred (Constitution Art. VI.1). "We'll delete the old code later" is only acceptable during explicit expand-contract phases, and the cleanup step must be in the plan.
- MANDATORY: the Out of Scope section names what is NOT part of this refactor — scope clarity prevents reviewer confusion
Gotchas
- "Tiny" is relative to the reviewer's context. A 20-line commit that touches the hot path is not tiny in practice — tiny means tractable, not short.
- Tests for refactors are often omitted with "the existing tests cover it". Verify by running the suite with coverage in the affected area, not by asking.
- Rebasing a long chain of tiny commits is painful when the target branch moves. Recommend landing the chain weekly and rebasing on
main before each review round.
- GitHub issue RFCs tend to get stale if the refactor drags. Add a "Status" line that updates with each landed commit so readers see progress without scrolling through comments.
- Expand-contract refactors with double-writes silently leak cost — both paths are live, both pay resources. Set a hard deadline in the plan for when the old path is removed.
When NOT to Use
- For executing a refactor directly — use
/refactor
- For architecture-level audit without a specific refactor in mind — use
/architecture-audit
- For creating a PRD (product requirements) — use
/write-a-prd
- For a plan without the GitHub RFC step — use
/plan
- For interface design of a single module — use
/design-an-interface
