refactor-plan
github/awesome-copilot
Plan multi-file refactors safely before making changes.
What is refactor-plan?
Create a detailed, phased refactor plan by investigating the codebase first, identifying dependencies and affected files, then output the plan for review. Use this when tackling cross-file refactors to sequence changes safely and avoid hidden coupling issues.
- Analyzes codebase to identify all affected files and dependencies
- Sequences changes in safe phases: types/interfaces, implementation, tests, cleanup
- Includes verification steps between phases to catch issues early
- Provides rollback and recovery steps for risky changes
- Outputs structured plan in markdown with clear ownership boundaries
- Waits for confirmation before implementing any code changes
How to install refactor-plan
npx skills add https://github.com/github/awesome-copilot --skill refactor-planHow to use refactor-plan
- 1.Ask the agent to plan a refactor, specifying the scope or files involved
- 2.The agent investigates the codebase without editing files
- 3.Review the generated plan, including phases, affected files, and rollback steps
- 4.Confirm you want to proceed with Phase 1 (or ask for adjustments)
- 5.Follow the agent through each phase, verifying steps as outlined
Use cases
- Refactoring a core module used across multiple files
- Renaming or restructuring API contracts before updating callers
- Migrating from one pattern to another (e.g., callbacks to promises)
- Splitting a large file into smaller, focused modules
- Updating shared types or interfaces with downstream impacts
- Backend and frontend engineers managing large codebases
- Teams coordinating multi-file changes across services
- Developers unfamiliar with a codebase planning safe refactors
- Code reviewers who need to understand refactor scope and sequence
refactor-plan FAQ
The skill will still produce the plan first and ask for confirmation before implementing, unless you explicitly say to continue without review after seeing the plan.
No. It only investigates and outputs a plan. You must confirm before the agent makes any edits.
The plan includes current state, target state, affected files with dependencies, phased steps with verification, rollback procedures, and identified risks.
If the request is too vague, the skill will ask clarifying questions instead of creating a plan, ensuring the refactor is well-scoped.
Full instructions (SKILL.md)
Source of truth, from github/awesome-copilot.
name: refactor-plan description: 'Create a concrete plan before starting a multi-file refactor. Use when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files; always investigate first, output the plan, and wait for confirmation before making code changes.'
Refactor Plan
Create a detailed plan before making any code changes.
Instructions
- Do not edit files while preparing the plan.
- Search the codebase to understand the current state. Read enough implementation, tests, configuration, and docs to make the plan specific to the repository.
- Identify affected files, ownership boundaries, dependencies, and likely hidden coupling.
- Plan changes in a safe sequence. Prefer contracts and types first, then implementations, then callers, then tests, then cleanup.
- Include verification steps between phases and a final validation command.
- Include rollback or recovery steps for the riskiest phases.
- Output the complete plan using the format below.
- Stop after the plan and ask for confirmation before implementing. If the user already asked you to implement, still produce the plan first and wait for confirmation unless they explicitly said to continue without review after the plan.
If the request is too ambiguous to plan safely, ask concise clarifying questions instead of editing files.
Output Format
## 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]
After the plan, ask: "Shall I proceed with Phase 1?"
Related skills
More from github/awesome-copilot and the wider catalog.
git-commit
Execute semantic git commits with conventional message analysis and intelligent staging.
excalidraw-diagram-generator
Generate Excalidraw diagrams from natural language descriptions.
documentation-writer
Create structured technical documentation using the Diátaxis framework for tutorials, how-to guides, references, and explanations.
gh-cli
GitHub CLI comprehensive reference for repositories, issues, PRs, Actions, projects, releases, and all GitHub operations from the command line.
prd
Generate comprehensive Product Requirements Documents with executive summaries, user stories, technical specs, and risk analysis.
refactor
Surgical code refactoring to improve maintainability without changing behavior.