vac-optimizer/.agents/skills/request-refactor-plan/SKILL.md

name, description

name	description
request-refactor-plan	Plan a refactor as small, independently verifiable changes and prepare it for the repository's configured issue tracker. Use for refactor plans or RFCs.

This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.

1. Use the supplied problem and ideas. Ask only for missing context that would materially affect the plan.

2. Explore the repo to verify their assertions and understand the current state of the codebase.

3. Compare relevant alternatives when there is a meaningful trade-off; preserve already settled choices.

4. Resolve consequential unknowns through a focused interview only when needed. Do not require a new interview for an actionable request.

5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.

6. Inspect existing test coverage and propose the checks needed to keep behavior stable. Ask the user only about constraints or desired behavior the repository cannot establish.

7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."

8. Return the requested plan. If the user also asked to file it, publish using the configured tracker without asking again. Otherwise keep it as a draft. If publication fails ambiguously, check for an existing issue before retrying; stop and preserve the draft when access or authority is missing. Use the following template as appropriate:

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 plan of small, verifiable changes, detailed enough to implement without artificial fragmentation. Follow the repository's development lifecycle policy when contracts and callers must change together; identify any shared integration gate explicitly.

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.