AutoGineer
Generated banner for Refactor Plan
Generated logo for Refactor Plan

Refactor Plan

GitHubOfficialFirst committed by jrkasprzykDistributed by GitHub

  • Skill
  • Workflow
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

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.
— the description by jrkasprzyk

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The refactor-plan skill provides a systematic approach to managing large-scale code changes. It mandates a thorough investigation of the codebase before any modifications occur, ensuring that dependencies, risks, and sequencing are understood. By requiring a detailed, step-by-step plan that includes verification and rollback strategies, it helps developers avoid breaking changes and maintain code integrity during complex refactoring tasks.

What it does

  • Analyzes the current codebase to identify affected files and dependencies.
  • Structures refactoring into logical phases: types/interfaces, implementation, tests, and cleanup.
  • Requires explicit verification steps for each phase of the refactor.
  • Provides a standardized template for documenting the refactor plan.
  • Includes a mandatory rollback strategy for high-risk operations.
  • Enforces a pause for user confirmation before any code is modified.

When to use it

  • When planning a refactor that spans multiple files or modules.
  • When you need to ensure a complex code change is safe and reversible.
  • When you want to document the sequence of changes for team visibility.
  • When you are unsure about the hidden coupling or dependencies of a specific code block.

Advantages

  • Reduces the risk of introducing regressions during large refactors.
  • Ensures all dependencies and side effects are considered before coding begins.
  • Provides a clear roadmap for complex tasks, improving developer focus.
  • Facilitates easier code reviews by providing a pre-defined plan.
  • Includes built-in safety measures like rollback steps.

Usage examples

“I need to rename the user authentication service and update all its callers. Can you help me plan this?”
The agent will investigate the current implementation, identify all dependent files, and output a structured plan for the rename, including verification steps for each phase.
“Refactor the database schema for our orders table across the backend.”
The agent will analyze the schema, list the affected files, and propose a phased execution plan that ensures data integrity and system stability.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/refactor-plan/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip refactor-plan.zip -d .agents/skills

Documentation by jrkasprzyk

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

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

Files

SKILL.md

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

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

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of jrkasprzykjrkasprzyk
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/refactor-plan · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jrkasprzyk

AutoGineer is not affiliated with or endorsed by jrkasprzyk or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download refactor-plan.zip