Invoke this skill when the user wants to create a refactor request. Follow these steps. You may skip steps you deem unnecessary.
-
Have the user describe in detail the problem they want to solve, as well as possible solution ideas.
-
Explore the repo, verify their assertions, and understand the current state of the codebase.
-
Ask them whether they have considered other options, and show them other options.
-
Interview the user about the implementation. Be very detailed and thorough.
-
Nail down the exact scope of the implementation. Figure out what you plan to change and what you will not change.
-
Check the test coverage for that area in the codebase. If coverage is insufficient, ask the user about their testing plans.
-
Plan to break the implementation into tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
-
Create a GitHub issue using the refactor plan. Use the following template for the issue description:
Problem Statement
The problem the developer faces, described from the developer's perspective.
Solution
The solution to the problem, described from the developer's perspective.
Commits
A very long, detailed implementation plan. Write it in plain English, breaking the implementation into the smallest possible commits. Each commit should keep the codebase in a working state.
Decision Document
A list of implementation decisions that have been made. This can include:
- Modules to build/modify
- Module interfaces to modify
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do not include specific file paths or code snippets. They may quickly become outdated.
Testing Decisions
A list of testing decisions that have been made. Include:
- A description of what makes a good test (test only 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 what is out of scope for this refactor.
Further Notes (optional)
Other notes about the refactor.