skills.rest
softspark
softsparkCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

refactor-plan

Create incremental refactor plans with tiny commits and GitHub issue RFCs.

161|21|Updated Mar 26, 2026
Search Tags:#planning#architecture#codebase#github#refactor#test-coverage#tiny-commits
One-click install
npx skills add https://github.com/softspark/ai-toolkit --skill refactor-plan-softspark
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactor-plan
Source: https://github.com/softspark/ai-toolkit/tree/main/app/skills/refactor-plan
Command: npx skills add https://github.com/softspark/ai-toolkit --skill refactor-plan-softspark

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Developers and teams need a reliable, interview-driven process to scope and execute refactors without creating large, risky pull requests; this Skill structures the conversation, verifies code, and produces a durable plan. It prevents scope creep, reduces review friction, and ensures each change is the smallest possible step that keeps the codebase working.

Core Features & Use Cases

  • Interview-driven scoping: Elicit detailed problem descriptions and implementation constraints from the developer before proposing changes.
  • Codebase exploration and verification: Use an Agent to inspect the codebase, check assumptions, and surface missing tests or risky areas.
  • Multiple approaches and trade-offs: Present three or more alternative refactoring strategies and discuss pros/cons for architectural impact.
  • Tiny-commit decomposition and RFC filing: Break the chosen approach into the smallest working commits and immediately file a GitHub issue RFC using gh issue create.
  • Use Case: Planning a gradual migration of an authentication module to a new service by interviewing the owner, checking tests, proposing options, and generating a commit-by-commit plan as an issue.

Quick Start

Invoke the refactor-plan skill with /refactor-plan authentication to start the interview, explore the codebase, propose alternatives, decompose into tiny commits, and file an RFC issue.

Frequently Asked Questions about refactor-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I plan a codebase refactor into small, safe commits?▼

To plan a codebase refactor into safe commits, use an interview-driven process to scope the problem, explore the codebase, evaluate three or more alternative approaches, and decompose changes into the smallest working steps before filing a GitHub issue RFC.

What is the best way to scope an architectural migration without causing scope creep?▼

The best way to scope an architectural migration and prevent scope creep is through an interview-driven scoping process that elicits detailed constraints, checks existing test coverage, evaluates alternatives, and breaks the work down into tiny incremental commits.

Does this refactor planning approach require existing test coverage in the codebase?▼

Yes, this approach verifies existing test coverage during codebase exploration to surface risky areas and missing tests, ensuring each tiny commit in the refactor plan keeps the codebase working without introducing large, risky pull requests.

How do I document a refactoring strategy and trade-offs for my development team?▼

To document a refactoring strategy, present three or more alternative approaches with pros and cons for architectural impact, then file the chosen incremental commit plan as an RFC issue directly on GitHub using the gh issue create command.

When should I avoid breaking changes into tiny commits during a codebase refactor?▼

You should avoid tiny commits only if your codebase lacks the test coverage needed to verify each step, as this method relies on checking assumptions and ensuring every small change keeps the codebase fully functional throughout the refactor.

Can I use this method to plan a gradual migration of an authentication module?▼

Yes, you can plan a gradual authentication module migration by interviewing the module owner, checking tests, proposing options, and generating a commit-by-commit refactor plan that is immediately filed as a GitHub issue RFC.

Related Skills

Explore More Software Engineering Skills→
LdotJdotLdotJdot
45

github

Automate GitHub repository management and PR/issue workflows via gh CLI.

Community
Intermediate
caeziumcaezium
2

request-refactor-plan

Plan refactors into tiny commits with RFC and GitHub issue templates.

Community
Intermediate
hffmnnjhffmnnj
39

atomic-commits

Create small, focused commits with one change per commit and meaningful messages.

Community
Basic
monlormonlor
1

request-refactor-plan

Create a detailed refactor plan with tiny commits and file it as a GitHub issue.

Community
Advanced