Request Refactor Plan
Turn a messy refactor idea into a scoped GitHub issue full of tiny, test-aware commits before anyone touches production code.
Overview
request-refactor-plan is an agent skill most often used in Ship (also Build pm, Operate iterate) that interviews you, validates the repo, and files a tiny-commit refactor plan as a GitHub issue.
Install
npx skills add https://github.com/mattpocock/skills --skill request-refactor-planWhat is this skill?
- Eight-step interview: problem capture, repo verification, alternatives, scope, tests, tiny commits, GitHub issue
- Explicit Martin Fowler guidance to keep each refactoring step small enough to always see the program working
- Built-in refactor-plan GitHub issue template with Problem Statement and implementation sections
- Repo exploration step to validate user assertions against actual code structure
- Checks test coverage in the affected area and surfaces testing gaps before planning merges
- 8-step refactor planning workflow
- GitHub issue template with Problem Statement section
Adoption & trust: 30.5k installs on skills.sh; 121k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You know the codebase needs a refactor but lack a shared, test-aware, bite-sized commit plan tracked in GitHub.
Who is it for?
Maintainers on GitHub-hosted repos who want RFC-style refactor plans with explicit scope and Fowler-style small steps.
Skip if: Greenfield prototypes with no tests and no intention to open a tracked issue before rewriting everything at once.
When should I use this skill?
User wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
What do I get? / Deliverables
You get a scoped refactor RFC issue with incremental commit steps ready for you or your agent to implement one merge at a time.
- GitHub issue with refactor plan and tiny-commit breakdown
- Documented scope in/out and testing notes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Refactor planning is canonically a Ship concern—safe incremental change after the product exists—though it also supports Build cleanup and Operate hardening. The skill produces a review-style RFC and commit ladder, which aligns with pre-merge quality gates rather than greenfield feature design.
Where it fits
Capture refactor scope for a tangled payments module before sprinting on new features.
File an issue that sequences extract-method commits ahead of a risky release branch.
Document a incremental plan to split a god-object after on-call pain, without a big-bang rewrite.
How it compares
Use for human-in-the-loop refactor RFCs on GitHub—not as a drop-in linter fixer or automatic codemod runner.
Common Questions / FAQ
Who is request-refactor-plan for?
Solo builders and indie teams who manage refactors in GitHub and want an agent to facilitate interviews, repo checks, and issue authoring.
When should I use request-refactor-plan?
In Ship review when planning structural cleanup before release; in Build pm when scheduling tech-debt epics; in Operate iterate when hardening a painful module—especially when the user asks for a refactoring RFC or incremental steps.
Is request-refactor-plan safe to install?
It encourages exploring your repository and creating GitHub issues—review the Security Audits panel on this page and avoid pasting secrets into issue bodies.
SKILL.md
READMESKILL.md - Request Refactor Plan
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. 1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions. 2. Explore the repo to verify their assertions and understand the current state of the codebase. 3. Ask whether they have considered other options, and present other options to them. 4. Interview the user about the implementation. Be extremely detailed and thorough. 5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change. 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. 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." 8. Create a GitHub issue with the refactor plan. Use the following template for the issue description: <refactor-plan-template> ## Problem Statement The problem that the developer is facing, from the developer's perspective. ## Solution The solution to the problem, from the developer's perspective. ## Commits 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. ## Decision Document A list of implementation decisions that were made. This can include: - The modules that will be built/modified - The interfaces of those modules that will be modified - Technical clarifications from the developer - Architectural decisions - Schema changes - API contracts - Specific interactions Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. ## Testing Decisions A list of testing decisions that were made. Include: - A description of what makes a good test (only test external behavior, not implementation details) - Which modules will be tested - Prior art for the tests (i.e. similar types of tests in the codebase) ## Out of Scope A description of the things that are out of scope for this refactor. ## Further Notes (optional) Any further notes about the refactor. </refactor-plan-template>