refactor-plan

Use it when:: You're about to refactor across several files and want the order of changes worked out before anything is edited.
It does:: Reads the code, tests, config and docs, maps affected files, dependencies and hidden coupling, then sequences changes: types first, then implementations, callers, tests and cleanup.
You get:: A Markdown plan: current and target state, a table of affected files, phased checklists each with a verify step, a rollback plan and risks.
Stops:: After the plan to ask "Shall I proceed with Phase 1?", even if you asked it to implement, unless you said to continue without review.

TL;DR

The skill keeps the agent's hands off the code while it plans. It searches the codebase and reads enough implementation, tests, configuration and docs to make the plan specific to your repository, then identifies the files involved, ownership boundaries, dependencies and coupling that could break. Changes are ordered so each phase builds on the last: contracts and types, then implementations, callers, tests and cleanup, with a verification step between phases and a final validation command. The riskiest phases get rollback or recovery steps. If the request is too vague to plan safely, it asks short clarifying questions instead. It edits no files: it outputs the plan, and implementation starts only once you confirm.

Summarizes the skill at 797337f.

npx skills add https://github.com/github/awesome-copilot --skill refactor-plan

skills.sh page Source on GitHub All skills from github/awesome-copilot

Total Downloads: 13,000 on skills.sh, Nov 9, 2026
Repo stars: 40,943 github/awesome-copilot
First seen: Feb 25, 2026 on skills.sh

Weekly Downloads

0% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	41
Sep 28	35
Oct 5	37
Oct 12	27
Oct 19	19
Oct 26	11
Nov 2	21
Nov 9	41

Category	category:planning category:software-engineering Make the agent question you and write the plan down before it writes code. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:workflow A multi-step process the agent follows: interview, debug, run a TDD loop, review.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:official A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates.
Topics	refactoring planning

SKILL.md

From github/awesome-copilot at 797337f. Checked daily, last changed Nov 6, 2026.

Frontmatter

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?"