request-refactor-plan

Request Refactor Plan

Use this skill when the user wants to create a refactor request. Skip steps only when they are clearly unnecessary.

Workflow

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 verify their assertions and understand the current state of the codebase.
3. Ask whether they have considered other options, and present other options to them.
4. Interview the user about the implementation. Be extremely detailed and thorough.
5. Hammer out the exact scope: what will change and what will not change.
6. Check test coverage for this area. If coverage is insufficient, ask the user what their testing plan is.
7. Break the implementation into tiny commits. Follow Martin Fowler's advice: make each refactoring step as small as possible, so you can always see the program working.
8. Create a GitHub issue with the refactor plan using gh issue create.

Scope Rules

• Keep every proposed commit small enough to leave the codebase working.
• Do not include specific file paths or code snippets in the final issue. They can become stale quickly.
• Separate implementation decisions from testing decisions.
• Make out-of-scope work explicit.

GitHub Issue Template

## Problem Statement

The problem that the developer is facing, from the developer's perspective.

## Solution

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

## Commits

A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.

## Decision Document

A list of implementation decisions that were made. This can include:

- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

## Testing Decisions

A list of testing decisions that were made. Include:

- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)

## Out of Scope

A description of the things that are out of scope for this refactor.

## Further Notes (optional)

Any further notes about the refactor.

Output Contract

Before creating the issue, show the user the final scope, tiny-commit plan, testing decisions, and out-of-scope list. After creating the issue, return the GitHub issue URL.