refactor-plan

Converts refactoring findings into a sequenced, risk-annotated plan of small reversible steps.

Updated Apr 16, 2026
One-click install
npx skills add https://github.com/real-case/marvin-toolkit --skill refactor-plan-real-case
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactor-plan
Source: https://github.com/real-case/marvin-toolkit/tree/main/plugins/marvin/skills/refactor-plan
Command: npx skills add https://github.com/real-case/marvin-toolkit --skill refactor-plan-real-case

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? After running a refactoring audit, teams have a list of findings but no safe order to execute them. This Skill turns findings registers into a sequenced plan where every step is small, behaviour-preserving, independently landable, and annotated with risk, rollback, and test coverage — while routing oversized work to the task pipeline instead of pretending it fits in one commit. ## Core Features & Use Cases - Findings re-verification: Re-checks each finding's file:line evidence against the current HEAD before planning, dropping stale or already-fixed items. - Size routing: Classifies findings as inline-plannable small steps or routes them to the task pipeline with a ready-to-use task-start input block. - Dependency-first sequencing: Orders steps by dependency then risk, with every step carrying rationale, rollback, tests, and effort fields. - Use Case: After running refactor-audit on a legacy module, ask for a plan covering findings F1 and F3; the Skill writes a plan file under .marvin/refactor/ with ordered steps and hands oversized items to the spec pipeline. ## Quick Start Ask the assistant to plan the refactoring for findings F1 and F3 from the latest audit report under .marvin/refactor/.

Frequently Asked Questions about refactor-plan

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

FAQPage Schema
How do I turn refactoring audit findings into an execution plan?▼

Run refactor-plan with the register file or finding IDs, such as specific F-numbers from an audit report. It re-verifies each finding's evidence, sequences small reversible steps by dependency and risk, and writes a plan file under .marvin/refactor/.

What happens to refactoring work too large for a single step?▼

Findings exceeding the small-step threshold, such as multi-module surgery or API changes, are routed to the task pipeline. The plan records a route entry with a ready-to-use task-start input containing goal, evidence, constraints, and definition of done.

Does refactor-plan modify source code?▼

No, the plan writes exactly one file, the plan document under .marvin/refactor/, and never touches source code. Execution is delegated to refactor-apply, which runs one step at a time under verification and coverage rails.

What if the audit report is older than the current code?▼

The plan re-verifies every finding's file:line evidence against HEAD before planning. Findings whose code moved or was already fixed are dropped with a note, and a mostly stale register triggers a recommendation to run a fresh audit.

Can I run refactor-plan without an existing findings register?▼

No, the plan consumes registers produced by refactor-audit or refactor-smells and does not re-discover findings. If no registers exist under .marvin/refactor/, it stops and directs you to run one of those scans first.