Create a concrete, evidence-backed plan before a multi-file refactor. Use this skill when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files, when hidden coupling is likely, or when implementation should wait for confirmation after a plan.
Investigate the repository without editing, define a safe phased refactor plan, include verification and rollback steps, then stop for confirmation before code changes unless the user explicitly authorized continuing after the plan.
When to invoke
"Plan this refactor before changing code."
"Sequence a multi-file refactor safely."
"What files are affected by this refactor?"
"Create a refactor plan and wait for approval."
"How should we roll back this risky refactor?"
Procedure
Do not edit files while preparing the plan.
Search the codebase to understand current implementation, tests, configuration, and documentation.
Identify affected files, ownership boundaries, dependencies, and likely hidden coupling.
Define current state and target state in repository-specific terms.
Sequence changes safely: contracts and types first, implementations second, callers third, tests fourth, cleanup last.
Add verification steps between phases and a final validation command.
Add rollback or recovery steps for the riskiest phases.
Output the complete plan using the template below.
Stop after the plan and ask: "Shall I proceed with Phase 1?"
If the request is too ambiguous to plan safely, ask concise clarifying questions instead of editing files.
Refactor planning criteria
Area
What to capture
Why it matters
Current state
How the code works now, including entry points and data flow.
Prevents plans based on assumptions.
Target state
The intended architecture or behavior after the refactor.
Keeps phases aligned to the user's goal.
Affected files
Modify/create/delete classification and dependencies.
Shows scope and review size.
Boundaries
API contracts, ownership, generated code, external integrations.
Avoids breaking callers or editing regenerated files.
Refactors often fail outside the obvious source files.
Verification
Checks after each phase plus final command.
Provides early failure points and confidence.
Rollback
How to undo risky phases.
Makes the plan executable under uncertainty.
Phase sequencing rules
Phase
Prefer
Avoid
Types and interfaces
Add or adjust contracts before implementations.
Editing callers first without a stable contract.
Implementation
Change internals behind the prepared contracts.
Mixing broad cleanup with behavior changes.
Callers
Migrate call sites in small groups with verification.
Big-bang updates with no intermediate checks.
Tests
Update or add tests that prove preserved behavior and new structure.
Weakening assertions to make the refactor pass.
Cleanup
Remove deprecated code and update documentation after validation.
Removing compatibility shims before all callers move.
Limits
Do not use this skill for single-file edits where no sequencing or hidden coupling exists.
Do not implement during the planning response unless the user explicitly said to continue without review after the plan.
If the user's instructions conflict with stopping for approval, follow the explicit latest user instruction and state the assumption in the plan.
Output template
## 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?
Quality gate
No files were edited while preparing the plan.
The plan cites repository-specific evidence from implementation, tests, configuration, or docs.
Current state, target state, affected files, phases, verification, rollback, and risks are all present.
Phases are sequenced from contracts/types to implementation, callers, tests, and cleanup unless a different order is justified.
Ambiguity is resolved with concise questions rather than speculative edits.
The response stops after the plan and asks "Shall I proceed with Phase 1?" unless explicitly authorized to continue.
1---2name: refactor-plan3description: Create a concrete, evidence-backed plan before a multi-file refactor. Use this skill when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files, when hidden coupling is likely, or when implementation should wait for confirmation after a plan.4---56<!-- Generated from harness/github-copilot/skills/refactor-plan/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Refactor plan910Investigate the repository without editing, define a safe phased refactor plan, include verification and rollback steps, then stop for confirmation before code changes unless the user explicitly authorized continuing after the plan.1112## When to invoke1314- "Plan this refactor before changing code."15- "Sequence a multi-file refactor safely."16- "What files are affected by this refactor?"17- "Create a refactor plan and wait for approval."18- "How should we roll back this risky refactor?"1920## Procedure21221. Do not edit files while preparing the plan.232. Search the codebase to understand current implementation, tests, configuration, and documentation.243. Identify affected files, ownership boundaries, dependencies, and likely hidden coupling.254. Define current state and target state in repository-specific terms.265. Sequence changes safely: contracts and types first, implementations second, callers third, tests fourth, cleanup last.276. Add verification steps between phases and a final validation command.287. Add rollback or recovery steps for the riskiest phases.298. Output the complete plan using the template below.309. Stop after the plan and ask: "Shall I proceed with Phase 1?"3132If the request is too ambiguous to plan safely, ask concise clarifying questions instead of editing files.3334## Refactor planning criteria3536| Area | What to capture | Why it matters |37| --- | --- | --- |38| Current state | How the code works now, including entry points and data flow. | Prevents plans based on assumptions. |39| Target state | The intended architecture or behavior after the refactor. | Keeps phases aligned to the user's goal. |40| Affected files | Modify/create/delete classification and dependencies. | Shows scope and review size. |41| Boundaries | API contracts, ownership, generated code, external integrations. | Avoids breaking callers or editing regenerated files. |42| Hidden coupling | Tests, config, docs, fixtures, serialization, DI, reflection, migrations. | Refactors often fail outside the obvious source files. |43| Verification | Checks after each phase plus final command. | Provides early failure points and confidence. |44| Rollback | How to undo risky phases. | Makes the plan executable under uncertainty. |4546## Phase sequencing rules4748| Phase | Prefer | Avoid |49| --- | --- | --- |50| Types and interfaces | Add or adjust contracts before implementations. | Editing callers first without a stable contract. |51| Implementation | Change internals behind the prepared contracts. | Mixing broad cleanup with behavior changes. |52| Callers | Migrate call sites in small groups with verification. | Big-bang updates with no intermediate checks. |53| Tests | Update or add tests that prove preserved behavior and new structure. | Weakening assertions to make the refactor pass. |54| Cleanup | Remove deprecated code and update documentation after validation. | Removing compatibility shims before all callers move. |5556## Limits5758- Do not use this skill for single-file edits where no sequencing or hidden coupling exists.59- Do not implement during the planning response unless the user explicitly said to continue without review after the plan.60- If the user's instructions conflict with stopping for approval, follow the explicit latest user instruction and state the assumption in the plan.6162## Output template6364```markdown65## Refactor Plan: [title]6667### Current State68[Brief description of how things work now]6970### Target State71[Brief description of how things will work after]7273### Affected Files74| File | Change Type | Dependencies |75|------|-------------|--------------|76| path | modify/create/delete | blocks X, blocked by Y |7778### Execution Plan7980#### Phase 1: Types and Interfaces81- [ ] Step 1.1: [action] in `file.ts`82- [ ] Verify: [how to check it worked]8384#### Phase 2: Implementation85- [ ] Step 2.1: [action] in `file.ts`86- [ ] Verify: [how to check]8788#### Phase 3: Tests89- [ ] Step 3.1: Update tests in `file.test.ts`90- [ ] Verify: Run `npm test`9192#### Phase 4: Cleanup93- [ ] Remove deprecated code94- [ ] Update documentation9596### Rollback Plan97If something fails:981. [Step to undo]992. [Step to undo]100101### Risks102- [Potential issue and mitigation]103104Shall I proceed with Phase 1?105```106107## Quality gate108109- [ ] No files were edited while preparing the plan.110- [ ] The plan cites repository-specific evidence from implementation, tests, configuration, or docs.111- [ ] Current state, target state, affected files, phases, verification, rollback, and risks are all present.112- [ ] Phases are sequenced from contracts/types to implementation, callers, tests, and cleanup unless a different order is justified.113- [ ] Ambiguity is resolved with concise questions rather than speculative edits.114- [ ] The response stops after the plan and asks "Shall I proceed with Phase 1?" unless explicitly authorized to continue.
Run npx skillmds@latest add paulasilvatech/refactor-plan in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Create a concrete, evidence-backed plan before a multi-file refactor. Use this skill when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files, when hidden coupling is likely, or when implementation should wait for confirmation after a plan. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
paulasilvatech (@paulasilvatech) published this skill. Their other Agent Skills are listed on their SkillMD profile.
paulasilvatech