The Workflow for the Request-Refactor-Plan Skill: A Complete 8-Step Guide

The request-refactor-plan skill guides AI assistants through an eight-step interview process to produce a detailed, commit-by-commit refactor plan suitable for filing as a GitHub issue.

The request-refactor-plan skill, maintained in the mattpocock/skills repository, provides a structured methodology for planning complex code refactors without breaking the codebase. Defined in request-refactor-plan/SKILL.md, the workflow extracts precise requirements through guided questioning and produces an actionable GitHub issue template that teams can execute immediately.

The 8-Step Interview Workflow

The skill operates as a sequential interview and analysis process. Each step builds upon the previous to ensure the resulting refactor plan is safe, incremental, and thoroughly validated.

Step 1: Gather Problem Details

The assistant begins by prompting the user for a long, detailed description of the problem they want to solve, including any initial solution ideas they may have. This establishes the foundational context for the entire refactoring exercise. According to request-refactor-plan/SKILL.md (lines 6–9), this step ensures the AI understands the developer's intent before examining the codebase.

Step 2: Explore the Repository

Next, the assistant examines the codebase to verify the user’s statements and to understand the current architecture, relevant modules, and existing implementations. This validation step, documented in SKILL.md (lines 10–12), prevents planning based on incorrect assumptions about the current code state.

Step 3: Consider Alternatives

The skill requires the assistant to ask whether the user has explored other possible solutions. If not, the assistant presents viable alternatives—such as a complete redesign, feature toggle, or different API design—to ensure the chosen refactor path is optimal. This is outlined in SKILL.md (lines 12–14).

Step 4: Deep Implementation Interview

The assistant conducts a thorough interview about the intended implementation. This includes drilling down into required behavior, edge cases, performance constraints, and integration points. As specified in SKILL.md (lines 14–16), this step captures the technical specifics needed to assess feasibility and risk.

Step 5: Scope Definition

The workflow mandates clearly defining the scope—what will be changed, what stays untouched, and any non-functional requirements. This prevents scope creep later in the process. The scope boundaries are established according to SKILL.md (lines 16–18).

Step 6: Verify Test Coverage

The assistant searches the repository for existing tests covering the target area. If coverage is lacking, the skill requires asking the user about their testing strategy—whether unit, integration, or property-based tests will be added. This verification step appears in SKILL.md (lines 18–20) and ensures safety nets are in place before modifications begin.

Step 7: Break Into Tiny Commits

The refactor is decomposed into a series of tiny, self-contained commits. Each commit must leave the codebase in a working state, following Martin Fowler’s “small steps” principle. This incremental approach, defined in SKILL.md (lines 20–22), allows teams to deploy or rollback at any point during the refactor.

Step 8: Create a GitHub Issue

Finally, the assistant populates a GitHub issue using the provided template. The issue includes sections for problem statement, solution, commit plan, decision document, testing decisions, out-of-scope items, and optional notes. Importantly, as noted in SKILL.md (lines 22–68), no raw file paths or code snippets are included to keep the plan future-proof against file renames or code shifts.

Installing the Skill

To add this workflow to your AI assistant setup, use the Skills CLI command referenced in the repository’s README.md (lines 39–42):

npx skills@latest add mattpocock/skills/request-refactor-plan

This installs the skill definition, making the eight-step workflow available for planning refactors in your codebase.

The Generated Refactor Plan

The output artifact is a GitHub issue body structured to guide implementation without ambiguity. The template includes:

• Problem Statement – The developer’s description of the current pain point.
• Solution – High-level description of the intended refactor.
• Commits – Numbered list of tiny, verifiable steps (e.g., "1. Create a failing test for the new behavior. 2. Extract interface from implementation...").
• Decision Document – Architectural choices, such as module ownership and public API signatures.
• Testing Decisions – Strategy details, like "test external behavior only" or "use table-driven tests."
• Out of Scope – Explicit exclusions, such as performance optimizations beyond the functional change.
• Further Notes – Optional additional considerations.

Key Source Files

File	Role
request-refactor-plan/SKILL.md	Defines the full workflow, interview prompts, and issue template structure.
README.md	Lists the skill among available options and documents the installation command.

Summary

• The request-refactor-plan skill follows an eight-step interview process defined in request-refactor-plan/SKILL.md to extract requirements and validate assumptions.
• It enforces incremental refactoring by decomposing work into tiny, working-state commits following Martin Fowler’s principles.
• The workflow validates existing test coverage and mandates testing strategies for untested code.
• Output is a future-proof GitHub issue containing a commit-by-commit plan, decision documentation, and explicit scope boundaries—without brittle file path references.

Frequently Asked Questions

What is the request-refactor-plan skill?

The request-refactor-plan skill is an AI assistant workflow defined in the mattpocock/skills repository. It provides an eight-step structured interview process designed to produce detailed, safe refactoring plans that can be filed as GitHub issues and executed by development teams.

How does the skill ensure safe refactoring?

The skill enforces safety through multiple validation gates: it requires exploring the repository to verify user assumptions (Step 2), mandates checking existing test coverage (Step 6), and insists on breaking the refactor into tiny, working-state commits (Step 7) that follow Martin Fowler’s “small steps” principle, ensuring the codebase remains functional throughout the process.

What is included in the generated GitHub issue?

The generated issue contains a Problem Statement, Solution overview, numbered Commits plan, Decision Document capturing architectural choices, Testing Decisions, explicit Out of Scope boundaries, and optional Further Notes. Notably, the template excludes raw file paths and code snippets to maintain future-proofing.

How do I add this skill to my AI assistant?

Install the skill using the Skills CLI by running npx skills@latest add mattpocock/skills/request-refactor-plan, as documented in the repository’s README.md (lines 39–42). This makes the workflow available for generating refactor plans in your projects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}