mcpField
R
refactor-plan

refactor-plan

github.com/helderbertoDevelopment2047 installsUpdated 6d ago
Repository

About refactor-plan

A development skill for planning code refactors, aimed at developers who need to clarify scope and approach before implementation. It breaks work into small, sequential steps that keep the codebase functional and records the plan in a GitHub issue.

Key features

  1. 01Review the problem and current code
  2. 02Define scope through discussion
  3. 03Compare approaches and trade-offs
  4. 04Split work into small functional commits
  5. 05Create a GitHub issue plan

Use cases

  1. 01Plan steps for a large refactor
  2. 02Check test coverage before refactoring
  3. 03Record an approved refactor plan in a GitHub issue

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/helderberto/agent-skills --skill refactor-plan

After installing, type/refactor-planin Claude Code to confirm it loaded.

Details

From the project README

Refactor Planning

Process

1. Understand Problem
  • Get detailed description from user
  • Ask about potential solutions they've considered
  • Explore codebase to verify current state
2. Define Scope
  • Interview user about implementation details
  • Present alternative approaches — each approach as an option with trade-offs in description; use preview to show code sketches when applicable. Use AskUserQuestion when available; otherwise present as a numbered list.
  • Define exactly what changes and what stays
  • Check test coverage in affected areas
3. Break Down Work

Apply Martin Fowler's principle: "Make each refactoring step as small as possible, so that you can always see the program working."

  • Create list of tiny commits
  • Each commit leaves codebase working
  • Sequential, not parallel changes
4. Create GitHub Issue
gh issue create --title "Refactor: <title>" --body "$(cat <<'EOF'
## Problem Statement

The problem from the developer's perspective.

## Solution

The approach from the developer's perspective.

## Commits

Detailed plan broken into the tiniest commits possible. Each leaves codebase working.

1. Add new interface type
2. Update service to accept new interface (keep old code path)
3. Add tests for new code path
4. Update consumers to use new interface
5. Remove old code path

## Implementation Decisions

- Modules to build/modify and their interfaces
- Architectural decisions
- Schema changes
- API contracts

Do NOT include file paths or code snippets -- they go stale.

## Testing Decisions

- What makes a good test (behavior, not implementation)
- Which modules need tests
- Prior art: similar test patterns in the codebase

## Out of Scope

What is explicitly not included.
EOF
)"

Rules

  • Each commit must keep codebase functional
  • No implementation details in plan (focus on behavior)
  • Verify test coverage before starting
  • Get user approval on approach

Error Handling

  • gh issue create fails -- run gh auth status to verify auth; offer to print as markdown instead
  • Test coverage insufficient -- note gaps and add "add tests for X" as first commit
  • Scope larger than expected -- revise plan with user before proceeding

See Also

  • tdd -- implement refactored code using test-driven development

Comments

Markdown supported