request-refactor-plan
by mattpocockrequest-refactor-plan helps agents turn a vague refactor idea into a scoped GitHub issue through user interview, repo inspection, option analysis, testing checks, and tiny commit planning.
This skill scores 76/100, which means it is a solid directory listing candidate for users who want structured refactor planning rather than a generic prompt. The repository provides enough real workflow guidance for an agent to trigger and run the skill credibly, but adopters should expect some execution details to remain implicit.
- The description is highly triggerable: it clearly targets refactor planning, RFC creation, and breaking work into safe incremental steps.
- It gives a concrete end-to-end workflow, including repo inspection, option exploration, scope setting, test-coverage review, and tiny-commit planning.
- It includes a specific final deliverable format by directing the agent to create a GitHub issue from a refactor-plan template.
- No support files, examples, or command details are provided, so issue creation and repo-specific execution still require agent guesswork.
- The workflow is interview-heavy and says steps may be skipped, which leaves edge-case handling and stopping criteria somewhat underspecified.
Overview of request-refactor-plan skill
What request-refactor-plan actually does
The request-refactor-plan skill helps you turn a vague refactoring idea into a reviewed, scoped, incremental plan that can be filed as a GitHub issue. Instead of jumping straight to code changes, it guides an agent through user interview, repository inspection, option analysis, scope definition, testing questions, and a commit-by-commit rollout plan.
Best fit for this skill
request-refactor-plan is best for developers and teams who already know a part of the codebase needs restructuring but do not yet have a safe execution plan. It is especially useful when you want to:
- prepare a refactor before implementation starts
- write a refactoring RFC or issue
- break a risky cleanup into tiny, reversible commits
- force clarity on scope, constraints, and testing before work begins
The real job-to-be-done
The real value is not “generate a refactor plan.” It is to reduce refactor risk by making the agent ask the right questions first, inspect the codebase, and produce a plan small enough to execute safely. That is a better fit than a generic prompt when the danger is unclear scope, hidden dependencies, or over-ambitious changes.
What makes request-refactor-plan different
The main differentiator is workflow discipline. The skill is opinionated about sequence:
- get a detailed problem description
- verify assumptions in the repo
- consider alternatives
- interview for implementation details
- define what is in and out of scope
- check test coverage and testing plans
- split work into tiny commits
- file the result as a GitHub issue
That structure makes request-refactor-plan for Refactoring more useful than a one-shot “write me a plan” request.
What users should know before installing
This skill is lightweight: the repository evidence shows only SKILL.md, with no extra scripts, templates, or helper files. That means adoption is easy, but output quality depends heavily on the quality of your repository context and answers during the interview. If you want a highly automated planner with supporting assets, this is not that. If you want a clear, reusable planning workflow, it is a strong fit.
How to Use request-refactor-plan skill
request-refactor-plan install
Install the request-refactor-plan skill in your skills-enabled environment with:
npx skills add mattpocock/skills --skill request-refactor-plan
If your setup already has the source available, read request-refactor-plan/SKILL.md first. In this case, that file is the entire implementation surface, so you do not need to hunt through extra support folders.
Read this file first
Start with:
SKILL.md
There are no companion README.md, metadata.json, rules/, or resources/ files surfaced for this skill, so most adoption questions should be answered from that single workflow document.
What input the skill needs from you
To use request-refactor-plan well, give the agent more than “please refactor X.” The skill works best when your first message includes:
- the affected area or files
- the current problem in developer terms
- why now
- known constraints
- tentative solution ideas
- any deadlines or compatibility requirements
- whether implementation is expected now or later
A weak input:
- “Help me refactor the auth module.”
A strong input:
- “I want a refactor plan for our auth module.
src/authmixes token parsing, session validation, and HTTP concerns. The current pain is duplicated logic across middleware and handlers, which is slowing feature work and creating inconsistent error handling. I think we may need to separate parsing from policy checks, but I’m not sure whether that should be done by extraction or by introducing a service layer. We cannot break existing API responses, and we need a plan that can be shipped in small commits.”
How request-refactor-plan usage works in practice
A practical request-refactor-plan usage flow looks like this:
- Tell the agent you want a refactor request or plan.
- Provide a detailed problem statement and rough solution ideas.
- Let the agent inspect the repository and validate your assumptions.
- Answer follow-up questions about alternatives, constraints, and scope.
- Confirm testing expectations for the affected code.
- Ask for the final output as a GitHub issue draft with tiny commit steps.
This is not a “fire and forget” skill. It is interview-driven by design.
How to turn a rough goal into a good prompt
Use a prompt structure like this:
- Problem: what hurts today
- Current area: which modules, services, or files are involved
- Suspected causes: coupling, duplication, unclear ownership, unstable tests, naming drift
- Constraints: backward compatibility, deadlines, team conventions
- Non-goals: what must not be changed
- Testing state: current tests, gaps, or uncertainty
- Desired output: GitHub issue, RFC, or commit-by-commit plan
Example:
“Use request-refactor-plan to help me prepare a refactor issue. Problem: src/payments mixes provider adapters with domain rules, making it hard to add providers safely. Current area: src/payments/* and checkout integration tests. Constraints: no API contract changes, no schema changes this sprint. Non-goals: do not redesign billing. Testing state: good unit coverage on adapters, weak integration coverage. Desired output: a GitHub issue with tiny commits and clear scope boundaries.”
Why repository inspection matters
The skill explicitly tells the agent to explore the repo and verify your assertions. That matters because many refactor plans fail when they are based only on the reporter’s mental model. Good use of request-refactor-plan means letting the agent check:
- whether the pain point is localized or cross-cutting
- which modules are actually coupled
- whether test coverage exists
- whether an “obvious” solution would create broader churn
If you prevent repository inspection, expect a much weaker plan.
How to handle alternatives and scope
A useful part of this skill is that it does not assume your first solution is correct. Expect the agent to ask whether other options exist and to propose alternatives. Treat that as a feature, not friction. The best refactor plans often come from narrowing the job:
- extract one responsibility instead of redesigning a subsystem
- improve tests before moving code
- isolate seams first, then refactor behavior
- defer architecture changes that are not required to solve the current pain
What the final output should look like
The request-refactor-plan guide is oriented toward a GitHub issue with at least these sections:
## Problem Statement## Solution- commit-by-commit implementation steps
- testing expectations
- clear scope boundaries
The most valuable output is usually not the prose summary. It is the tiny-commit breakdown, because that turns a scary refactor into executable work.
When to use this instead of a generic prompt
Use request-refactor-plan when you need planning rigor. A generic prompt may produce a plausible-sounding plan, but this skill is stronger when you need:
- validation against the actual repository
- explicit scope negotiation
- alternatives surfaced before implementation
- test strategy discussion
- a sequence of very small commits rather than a broad rewrite
Common adoption blocker
The main blocker is under-specifying the problem. If your team cannot clearly explain the developer pain, constraints, and non-goals, the skill will still ask good questions, but the plan may stay too abstract to be actionable. In practice, the quickest path to value is to bring one real pain point and one concrete code area, not a broad “clean up the architecture” request.
request-refactor-plan skill FAQ
Is request-refactor-plan only for large refactors?
No. It is often more valuable for medium refactors that feel deceptively simple. Large refactors benefit too, but the skill shines when you want to avoid turning a moderate cleanup into an unbounded redesign.
Is this beginner-friendly?
Yes, if a beginner can describe the problem and answer questions about the codebase. The skill adds structure that juniors often need. But it does not replace repository understanding; weak answers will limit plan quality.
How is request-refactor-plan different from asking for a refactor directly?
Direct refactor requests push the agent toward implementation. request-refactor-plan slows that down on purpose. It focuses on problem framing, alternatives, scope, tests, and incremental delivery before code changes begin.
Does the request-refactor-plan skill write code?
Its primary purpose is planning, not implementation. You can use the resulting issue or commit plan to guide later coding work, but the skill itself is centered on producing a safe, concrete refactor request.
When should I not use request-refactor-plan for Refactoring?
Skip it when:
- the change is tiny and obvious
- you already have a complete, reviewed implementation plan
- you need immediate code edits more than planning
- the work is really a feature design or architecture proposal, not a refactor
In those cases, a more direct prompt may be faster.
Does it require GitHub?
The workflow ends by creating a GitHub issue, so GitHub is the natural fit. Even if you use another tracker, the issue template structure is still useful as a planning artifact you can copy elsewhere.
Are there hidden files or automation helpers to learn?
Not from the surfaced repository evidence. This skill appears to be a single-document workflow. That makes it easy to understand, but it also means you should not expect extra automation, schemas, or enforcement rules.
How to Improve request-refactor-plan skill
Give sharper problem statements
The fastest way to improve request-refactor-plan results is to describe the pain from a developer workflow perspective, not as a vague quality complaint. Better than “the code is messy”:
- what change is hard today
- what duplication or coupling causes it
- what breaks confidence
- what cost the current structure creates
That gives the agent something concrete to validate.
Name explicit non-goals
Many refactor plans become bloated because non-goals are missing. Tell the agent what must stay unchanged:
- public APIs
- database schema
- user-facing behavior
- performance profile
- release timing
This helps request-refactor-plan produce a smaller and more realistic sequence.
Provide file and module anchors
Even if the agent will inspect the repo, you should point it to likely hotspots. Useful anchors include:
- directories
- service names
- entry points
- failing tests
- duplicated implementations
This reduces guesswork and improves the repo-verification step.
Be honest about test coverage
The skill specifically checks whether this part of the codebase is tested. If coverage is weak, say so early. Strong outputs often depend on deciding whether to:
- add characterization tests first
- expand integration coverage
- defer risky moves until safety nets exist
Hiding test gaps leads to overconfident plans.
Ask for tiny commits, not just phases
The skill already pushes toward small steps, but you can improve output by requesting commit-sized granularity. A phase like “extract service layer” is still too large. Better commit framing looks like:
- add characterization tests for current behavior
- extract helper without behavior change
- redirect one call site
- remove dead path after tests pass
That level is where refactoring risk actually drops.
Force alternative evaluation
A common failure mode is locking into your first solution too early. Improve the request-refactor-plan skill by explicitly asking the agent to compare at least two approaches and explain why one is safer, smaller, or more reversible in your repo.
Tighten the first draft after review
After the first plan, do one more iteration with targeted feedback:
- which steps still feel too big
- where the scope is unclear
- what assumptions need verification
- which testing steps are underspecified
A short second pass usually improves actionability more than making the first prompt longer.
Watch for these common failure modes
The main quality problems to catch are:
- scope that quietly expands into redesign
- commit steps that are still too large
- missing test strategy
- assumptions not grounded in repository inspection
- solution text that sounds good but does not map to real files or modules
If you see those, ask the agent to rewrite the plan around verified code areas and smaller units of change.
Best way to operationalize the output
Once request-refactor-plan gives you a strong issue draft, treat it as a working execution document:
- review it with the team
- trim or split oversized commits
- assign owners for risky steps
- link affected tests and modules
- update the issue as reality changes
That is the highest-value use of the skill: not just generating a plan, but making a refactor easier to start, safer to execute, and easier to review.