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

> Master the request refactor plan skill with this 8-step guide. Learn how AI assistants create detailed refactor plans for GitHub issues. Boost your development workflow today.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: how-to-guide
- Published: 2026-04-04

---

**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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/README.md) (lines 39–42):

```bash
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`](https://github.com/mattpocock/skills/blob/main/request-refactor-plan/SKILL.md) | Defines the full workflow, interview prompts, and issue template structure. |
| [`README.md`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/README.md) (lines 39–42). This makes the workflow available for generating refactor plans in your projects.