Request Refactor Plan
- 196k installs
- 200k repo stars
- Updated July 31, 2026
- mattpocock/skills
request-refactor-plan is a Claude Code skill that interviews the developer about a refactor, verifies assertions against the repo, and files a GitHub issue breaking the work into tiny always-working commits.
About
request-refactor-plan turns a refactoring idea into a detailed, filed GitHub issue through an 8-step interview. The agent asks for a long problem description, explores the repo to verify the developer's assertions, surfaces alternative options, interviews thoroughly on implementation, hammers out exact scope, and checks test coverage - asking for a testing plan where coverage is thin. It then breaks the work into the tiniest possible commits, following Martin Fowler's advice that each step should leave the program visibly working, and files an issue using a fixed template: problem statement, solution, commit plan, decision document, testing decisions, and out-of-scope, with file paths and code snippets deliberately excluded. This skill is deprecated upstream in mattpocock/skills and kept for reference only.
- 8-step process: problem description, repo exploration to verify assertions, alternatives, detailed interview, scoping, t
- Quotes Martin Fowler: make each refactoring step as small as possible so you can always see the program working
- Checks existing test coverage and asks about testing plans when coverage is insufficient
- Issue template includes problem statement, solution, commits, decision document, testing decisions, and out-of-scope sec
- Bans specific file paths and code snippets from the plan because they go stale quickly
Request Refactor Plan by the numbers
- 195,614 all-time installs (skills.sh)
- +21,886 installs in the week ending Aug 2, 2026 (Skillselion tracking)
- Ranked #29 of 3,280 Productivity & Planning skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 3, 2026 (Skillselion catalog sync)
request-refactor-plan capabilities & compatibility
- Works with
- github
- Use cases
- refactoring · planning · project management
- Runs
- Runs locally
- Pricing
- Free
What request-refactor-plan says it does
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."
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
npx skills add https://github.com/mattpocock/skills --skill request-refactor-planAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 196k |
|---|---|
| repo stars | ★ 200k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 31, 2026 |
| Repository | mattpocock/skills ↗ |
How do you break a risky refactor into safe, reviewable steps instead of one big rewrite that leaves the codebase broken mid-flight?
Interview the developer about a refactor, verify claims against the repo, and file a GitHub issue breaking the work into tiny always-working commits.
Who is it for?
Developers facing a non-trivial refactor who want it scoped, de-risked, and broken into always-working commits before anyone edits code.
Skip if: Not for executing the refactor itself or for small changes that do not need a plan; the output is a planning issue, not code. Deprecated upstream.
When should I use this skill?
When the user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
What you get
A filed GitHub issue containing the commit-by-commit refactor plan, decision document, testing decisions, and explicit out-of-scope boundaries.
- GitHub issue containing the refactor plan
By the numbers
- 8-step process from problem description to filed GitHub issue
Files
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>
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.691k196kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.585k196k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.493kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.493kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).493kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.493kForks & variants (2)
Request Refactor Plan has 2 known copies in the catalog totaling 3 installs. They canonicalize to this original listing.
- vinvcn - 2 installs
- timothyvang - 1 installs
How it compares
Use instead of ad-hoc refactoring conversations; the structured interview plus repo verification yields a durable plan with tiny always-working commits.
FAQ
What does request-refactor-plan produce?
A GitHub issue with a fixed template: problem statement, solution, a long commit-by-commit plan in plain English, a decision document, testing decisions, and an out-of-scope section - no file paths or code snippets, which go stale.
When should I use request-refactor-plan?
When you want to plan a refactor, write a refactoring RFC, or break a risky change into safe incremental steps before touching code. Note it is deprecated upstream and kept for reference.
How does it handle testing?
It checks the codebase for existing test coverage of the affected area; if coverage is insufficient it asks about your testing plans, and the issue records testing decisions including which modules get tested and prior art.
Is Request Refactor Plan safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.