refactor-plan
Plan a multi-file refactor with proper sequencing and rollback steps
Best use case
refactor-plan is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Plan a multi-file refactor with proper sequencing and rollback steps
Teams using refactor-plan should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/refactor-plan/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How refactor-plan Compares
| Feature / Agent | refactor-plan | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Plan a multi-file refactor with proper sequencing and rollback steps
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Refactor Plan
Create a detailed plan for this refactoring task.
## Refactor Goal
{{refactor_description}}
## Instructions
1. Search the codebase to understand current state
2. Identify all affected files and their dependencies
3. Plan changes in a safe sequence (types first, then implementations, then tests)
4. Include verification steps between changes
5. Consider rollback if something fails
## Output Format
```markdown
## Refactor Plan: [title]
### Current State
[Brief description of how things work now]
### Target State
[Brief description of how things will work after]
### Affected Files
| File | Change Type | Dependencies |
|------|-------------|--------------|
| path | modify/create/delete | blocks X, blocked by Y |
### Execution Plan
#### Phase 1: Types and Interfaces
- [ ] Step 1.1: [action] in `file.ts`
- [ ] Verify: [how to check it worked]
#### Phase 2: Implementation
- [ ] Step 2.1: [action] in `file.ts`
- [ ] Verify: [how to check]
#### Phase 3: Tests
- [ ] Step 3.1: Update tests in `file.test.ts`
- [ ] Verify: Run `npm test`
#### Phase 4: Cleanup
- [ ] Remove deprecated code
- [ ] Update documentation
### Rollback Plan
If something fails:
1. [Step to undo]
2. [Step to undo]
### Risks
- [Potential issue and mitigation]
```
Shall I proceed with Phase 1?Related Skills
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
plan-writing
Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
legacy-migration-planner
Use when planning legacy system migrations, codebase modernization, monolith decomposition, microservices consolidation, cross-language rewrites, or framework upgrades. Invoke for strangler fig pattern, incremental migration strategy, or refactoring roadmaps. Do NOT use for domain analysis (use domain-analysis), component sizing (use component-identification-sizing), or step-by-step decomposition plans (use decomposition-planning-roadmap).
decomposition-planning-roadmap
Creates step-by-step decomposition plans and migration roadmaps for breaking apart monolithic applications. Use when asking "what order should I extract services?", "plan my migration", "create a decomposition roadmap", "prioritize what to split", "monolith to microservices strategy", or tracking decomposition progress. Do NOT use for domain analysis (use domain-analysis) or component sizing (use component-identification-sizing).
cross-repo-plan
Creates and tracks implementation plans that span multiple repositories. Extends the single-repo plan model with a coordinator document that tracks per-repo progress, cross-repo dependencies, and execution order.
java-refactoring-extract-method
Refactoring using Extract Methods in Java Language
create-github-issues-feature-from-implementation-plan
Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.
update-plan
Update an existing plan's status, todo list, and phase progress. Tracks what was done, updates completion status, and maintains the changelog. Use this skill during or after working on a plan phase to keep planning artifacts current.
sdd:plan
Refine, parallelize, and verify a draft task specification into a fully planned implementation-ready task
java-refactoring-remove-parameter
Refactoring using Remove Parameter in Java Language
executing-plans
Use when you have a written implementation plan to execute in a separate session with review checkpoints
concise-planning
Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist.