Request Refactor Plan
Interview the developer, explore the repo, and file a GitHub issue with a Fowler-style tiny-commit refactor plan before anyone touches production code.
Overview
request-refactor-plan is an agent skill most often used in Build (also Ship, Operate) that turns a refactor goal into a scoped GitHub issue with tiny, always-working commits and explicit testing decisions.
Install
npx skills add https://github.com/vinvcn/mattpocock-skills-zh-cn --skill request-refactor-planWhat is this skill?
- Structured user interview: problem, solution ideas, and rejected alternatives before coding
- Repo exploration step validates assertions against the current codebase state
- Implementation split into the smallest possible commits that keep the app working (Martin Fowler style)
- GitHub issue template: Problem Statement, Solution, Commits, Decision Document, Testing Decisions
- Explicit in-scope vs out-of-scope boundary before the commit list is finalized
- GitHub issue template includes five sections: Problem Statement, Solution, Commits, Decision Document, Testing Decisions
Adoption & trust: 1 installs on skills.sh; 498 GitHub stars.
What problem does it solve?
You know the codebase needs a large refactor but fear a big-bang change with no agreed scope, tests, or rollback-friendly steps.
Who is it for?
Solo builders planning multi-file refactors, module extractions, or API shape changes who want an issue-backed RFC before editing.
Skip if: Trivial one-commit fixes, emergencies that must ship immediately without planning, or work when the refactor spec is already approved and only execution remains.
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 filed GitHub issue with problem/solution narrative, decision log, testing stance, and an ordered micro-commit plan ready for incremental implementation.
- GitHub issue with refactor plan and decision document
- Ordered micro-commit implementation list
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Refactor planning usually starts when you are actively changing the product codebase (Build), but the same RFC discipline helps pre-merge review and ongoing tech-debt iteration. The skill produces a scoped implementation plan and issue—product/engineering planning work—so the canonical shelf is build → pm.
Where it fits
Draft a tiny-commit plan before extracting a god module into bounded packages.
Attach a refactor issue so reviewers see decision log and commit order before the PR series lands.
File tech-debt payoff work as an issue with explicit non-goals so iteration does not sprawl.
How it compares
Structured refactor RFC and issue filing—not an ad-hoc “just rename everything” chat session.
Common Questions / FAQ
Who is request-refactor-plan for?
Developers and agent users who want a disciplined refactor plan with GitHub-visible scope, decisions, and incremental commits before changing code.
When should I use request-refactor-plan?
In Build when scoping a refactor; in Ship when preparing reviewable incremental PRs; in Operate when paying down tech debt with a documented commit sequence.
Is request-refactor-plan safe to install?
It guides interviews and issue creation; review the Security Audits panel on this page before granting repo and GitHub access to your agent.
SKILL.md
READMESKILL.md - Request Refactor Plan
当用户想创建 refactor request 时调用此 skill。按以下步骤执行。你可以跳过你认为不必要的步骤。 1. 让用户详细描述他们想解决的问题，以及可能的 solution ideas。 2. 探索 repo，验证他们的 assertions，并理解 codebase 当前状态。 3. 询问他们是否考虑过其他 options，并向他们展示其他 options。 4. 围绕 implementation 访谈用户。要非常详细、彻底。 5. 敲定 implementation 的 exact scope。弄清你计划改什么，以及不改什么。 6. 在 codebase 中检查该区域的 test coverage。如果 coverage 不足，询问用户的 testing plans。 7. 把 implementation 拆成 tiny commits 的计划。记住 Martin Fowler 的建议：“make each refactoring step as small as possible, so that you can always see the program working.” 8. 使用 refactor plan 创建 GitHub issue。issue description 使用下面模板： <refactor-plan-template> ## Problem Statement developer 面对的问题，从 developer 视角描述。 ## Solution 问题的 solution，从 developer 视角描述。 ## Commits 一份很长、详细的 implementation plan。用 plain English 写，把 implementation 拆到尽可能小的 commits。每个 commit 都应让 codebase 保持 working state。 ## Decision Document 已作出的 implementation decisions 列表。可以包括： - 将 build/modify 的 modules - 将 modify 的 module interfaces - 来自 developer 的 technical clarifications - Architectural decisions - Schema changes - API contracts - Specific interactions 不要包含具体 file paths 或 code snippets。它们可能很快过时。 ## Testing Decisions 已作出的 testing decisions 列表。包括： - 什么是好测试的描述（只测试 external behavior，不测试 implementation details） - 哪些 modules 会被测试 - 测试的 prior art（即 codebase 中类似类型的 tests） ## Out of Scope 本 refactor 范围外事项的描述。 ## Further Notes (optional) 关于 refactor 的其他 notes。 </refactor-plan-template>