---
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
1. **Gathers** detailed problem description from user
2. **Explores** the codebase to verify assertions
3. **Presents** alternative approaches (>=3 options)
4. **Interviews** about implementation details
5. **Checks** test coverage of affected area
6. **Breaks** into tiny commits (Martin Fowler: each step keeps codebase working)
7. **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
<refactor-plan-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.
</refactor-plan-template>
## 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`