request-refactor-plan
bymattpocock· 47 skills
Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
How to install request-refactor-plan?
mattpocock/skills/request-refactor-plan
$npx -y skills add mattpocock/skills --skill request-refactor-planInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Run `npx skills use "https://github.com/mattpocock/skills" --skill "mattpocock/skills/request-refactor-plan"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.
Use the skills in "https://github.com/mattpocock/skills" that are relevant to the current task. Run `npx skills add "https://github.com/mattpocock/skills"` and select the relevant skills, then follow their instructions.
SKILL.md
| 1 | This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary. |
| 2 | |
| 3 | 1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions. |
| 4 | |
| 5 | 2. Explore the repo to verify their assertions and understand the current state of the codebase. |
| 6 | |
| 7 | 3. Ask whether they have considered other options, and present other options to them. |
| 8 | |
| 9 | 4. Interview the user about the implementation. Be extremely detailed and thorough. |
| 10 | |
| 11 | 5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change. |
| 12 | |
| 13 | 6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are. |
| 14 | |
| 15 | 7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working." |
| 16 | |
| 17 | 8. Create a GitHub issue with the refactor plan. Use the following template for the issue description: |
| 18 | |
| 19 | <refactor-plan-template> |
| 20 | |
| 21 | ## Problem Statement |
| 22 | |
| 23 | The problem that the developer is facing, from the developer's perspective. |
| 24 | |
| 25 | ## Solution |
| 26 | |
| 27 | The solution to the problem, from the developer's perspective. |
| 28 | |
| 29 | ## Commits |
| 30 | |
| 31 | A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state. |
| 32 | |
| 33 | ## Decision Document |
| 34 | |
| 35 | A list of implementation decisions that were made. This can include: |
| 36 | |
| 37 | - The modules that will be built/modified |
| 38 | - The interfaces of those modules that will be modified |
| 39 | - Technical clarifications from the developer |
| 40 | - Architectural decisions |
| 41 | - Schema changes |
| 42 | - API contracts |
| 43 | - Specific interactions |
| 44 | |
| 45 | Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. |
| 46 | |
| 47 | ## Testing Decisions |
| 48 | |
| 49 | A list of testing decisions that were made. Include: |
| 50 | |
| 51 | - A description of what makes a good test (only test external behavior, not implementation details) |
| 52 | - Which modules will be tested |
| 53 | - Prior art for the tests (i.e. similar types of tests in the codebase) |
| 54 | |
| 55 | ## Out of Scope |
| 56 | |
| 57 | A description of the things that are out of scope for this refactor. |
| 58 | |
| 59 | ## Further Notes (optional) |
| 60 | |
| 61 | Any further notes about the refactor. |
| 62 | |
| 63 | </refactor-plan-template> |
Related
6 picksType
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.Jul 2026
- domain-modelingBuild and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision,…Jul 2026
- caveman-reviewUltra-compressed code review comments. Cuts noise from PR feedback while preserving the actionable signal. Each comment is one line: location, problem, fix.Jul 2026
- codebase-designShared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a…Jul 2026
- code-reviewReview the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding…Jul 2026
- resolving-merge-conflictsUse when you need to resolve an in-progress git merge/rebase conflict.Jul 2026
