playbooks

home / skills / mattpocock / course-video-manager / create-refactor-rfc

create-refactor-rfc skill

/.claude/skills/create-refactor-rfc

This skill helps you craft a comprehensive RFC for a refactor by guiding problem analysis, module design, and detailed behavioral stories.

npx playbooks add skill mattpocock/course-video-manager --skill create-refactor-rfc

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: create-refactor-rfc
description: Use this skill to create an RFC for a refactor.
---

This skill will be invoked when the user wants to create an RFC for a refactor. Follow the steps below:

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 understand the current state of the codebase and in what ways the codebase violates the values.

3. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.

A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.

Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.

4. Interview the user about changes they would like to see made. Be extremely detailed and thorough.

5. Create a RFC for the changes that will be made. The RFC should be structured like so:

<rfc-template>

## Problem Statement

The problem that the developer is facing, from the developer's perspective. This should be readable by a newcomer to the project.

## Solution

The solution to the problem, from the developer's perspective.

## Implementation

This section should explain the rough API changes (internal and external), package changes, etc. The goal is to give an idea to reviews about the subsystems that require change and the surface area of those changes.

## Behaviors

A LONG, numbered list of user stories. Each user story should be in the format of:

1. <feature-or-module>: <description-of-behavior>

<user-story-example>
1. Clip Reducer: When an ADD_CLIP action is dispatched, the clip is added to the state with a unique ID.
</user-story-example>

Do NOT suggest an ordering of the tasks. The ordering will be determined later based on priority.

This list of user stories should be extremely extensive and cover all aspects of the refactor.

</rfc-template>

5. Submit the RFC as a GitHub issue.

Overview

This skill creates a thorough RFC for a planned code refactor and files it as a GitHub issue. It guides you through problem elicitation, repository inspection, modular design, and an exhaustive set of user-story behaviors needed for reviewers and implementers. The output is a ready-to-review RFC matching the provided template and repository context.

How this skill works

I first ask for a long, detailed description of the problem you want to solve and any solution ideas you already have. I then inspect the repository to identify current code structure, violations of project values, and candidates for deep module extraction. Next I propose major modules to build or modify, interview you about desired changes and test priorities, and produce an RFC that follows the required template. Finally I create a GitHub issue containing the RFC so work can be tracked and reviewed.

When to use it

  • You plan a non-trivial refactor that needs shared understanding before implementation.
  • You need to extract or redesign core modules into deep, easily testable components.
  • You want an exhaustive, review-ready specification of behavior and API changes.
  • You must create a single authoritative artifact to drive PRs and implementation.
  • You want to collect stakeholder feedback before starting code changes.

Best practices

  • Provide a detailed problem description and any existing constraints or alternatives.
  • Grant repository access or point to key files so I can analyze current structure.
  • Decide in advance which modules require unit tests and which need integration tests.
  • Favor extracting deep modules with small, stable interfaces for easier testing.
  • Validate the proposed modules and behavior list before I generate the final RFC and issue.

Example use cases

  • Refactoring a large reducer/flux store into small, testable state modules.
  • Splitting a monolithic service into domain-specific services with clear APIs.
  • Converting mixed UI/business logic into presentation and domain layers.
  • Rewriting a legacy TypeScript module to improve type safety and testability.
  • Standardizing an error-handling approach across multiple packages.

FAQ

Do you need full repo access to generate the RFC?

I need visibility on the code files relevant to the refactor. Point me to files or provide read access to the repository for a thorough inspection.

Will you include tests in the RFC?

I will list which modules should have tests and describe test targets and interfaces. You choose which modules you want concrete test plans for before finalizing the RFC.