Refactor Plan
Sequence a safe multi-file refactor with investigation, phased steps, verification, and rollback—without editing code until you confirm the plan.
Overview
Refactor Plan is an agent skill most often used in Ship (also Build, Operate) that investigates the repo and outputs a phased refactor plan before any multi-file code changes.
Install
npx skills add https://github.com/github/awesome-copilot --skill refactor-planWhat is this skill?
- Hard rule: do not edit files while preparing the plan
- Safe sequence: contracts and types first, then implementations, callers, tests, cleanup
- Plan includes verification between phases, final validation command, and rollback for risky steps
- Structured markdown output: current state, target state, affected files, phased tasks
- Stops after the plan unless user explicitly skips post-plan confirmation
- Eight-step instruction flow ending with stop-for-confirmation before implementation
- Phased order: contracts/types → implementations → callers → tests → cleanup
Adoption & trust: 11.1k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want a large refactor but fear hidden coupling and no clear order of operations, so one careless edit breaks tests or production paths.
Who is it for?
Solo maintainers facing multi-file structural changes who want repository-specific sequencing and an explicit pause before edits.
Skip if: Single-line fixes, exploratory spikes where you want immediate edits, or cases where you already have an approved implementation plan and only need execution.
When should I use this skill?
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.
What do I get? / Deliverables
You get a confirmation-gated refactor plan with phased tasks, verification, and rollback—then you approve before the agent implements.
- Markdown refactor plan (current state, target state, affected files, phased tasks, verification, rollback)
- Explicit confirmation checkpoint before implementation
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship review because the skill gates risky change behind an explicit plan and confirmation, matching pre-change quality discipline even though refactors touch Build work. Review subphase reflects investigate-first, no edits during planning, and stop-for-confirmation before implementation—the same bar as serious code review before merge.
Where it fits
Draft a phased extraction plan and pause for approval before a pre-release structural cleanup.
Map service boundaries and type contracts before moving handlers into a new package layout.
Plan component library migration with test updates between each folder wave.
Sequence tech-debt refactors with rollback steps so production hotfix paths stay intact.
How it compares
Use instead of letting the agent refactor across files inline without an investigated, sequenced plan.
Common Questions / FAQ
Who is refactor-plan for?
Indie developers and small teams using coding agents who need a safe, repo-aware sequence before multi-file refactors.
When should I use refactor-plan?
In Ship review before risky merges; in Build backend or frontend when restructuring modules; in Operate iterate when paying down tech debt without breaking deploys.
Is refactor-plan safe to install?
The skill itself discourages premature edits; still review generated plans and confirm before implementation, and check Security Audits on this Prism page for the package source.
SKILL.md
READMESKILL.md - Refactor Plan
# Refactor Plan Create a detailed plan before making any code changes. ## Instructions 1. Do not edit files while preparing the plan. 2. Search the codebase to understand the current state. Read enough implementation, tests, configuration, and docs to make the plan specific to the repository. 3. Identify affected files, ownership boundaries, dependencies, and likely hidden coupling. 4. Plan changes in a safe sequence. Prefer contracts and types first, then implementations, then callers, then tests, then cleanup. 5. Include verification steps between phases and a final validation command. 6. Include rollback or recovery steps for the riskiest phases. 7. Output the complete plan using the format below. 8. 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 ```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] ``` After the plan, ask: "Shall I proceed with Phase 1?"