safe-refactor

Restructures code while preserving behavior through verification-bracketed structural edits.

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/bittlinkm/claude-setup --skill safe-refactor-bittlinkm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: safe-refactor
Source: https://github.com/bittlinkm/claude-setup/tree/main/skills/safe-refactor
Command: npx skills add https://github.com/bittlinkm/claude-setup --skill safe-refactor-bittlinkm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Structural code changes like extractions, consolidations, and ownership moves often introduce subtle regressions because behavior verification is skipped or done inconsistently. This Skill enforces a disciplined refactoring workflow where verification brackets every structural edit. ## Core Features & Use Cases - Behavior-Preservation Boundary: Defines the scope of what must stay unchanged—public interfaces, failure behavior, ordering, and compatibility—before any edit begins. - Incremental Ownership Moves: Moves one ownership boundary at a time while keeping every intermediate state buildable and testable. - Verification Bracketing: Runs the same proof before and after the change, stopping only when behavior matches and the requested structure is achieved. - Use Case: When extracting a shared module from a monolith, use this Skill to keep feature changes out of the refactor, preserve the public API, and confirm tests pass identically at each step. ## Quick Start Use safe-refactor to extract this duplicated logic into a shared module while preserving existing behavior and keeping tests green.

Frequently Asked Questions about safe-refactor

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

FAQPage Schema
How do I refactor code without changing its behavior?

Define a behavior-preservation boundary first, then run the same verification before and after each structural edit. Keep feature changes out of the refactor and move one ownership boundary at a time so every intermediate state stays buildable and testable.

How to safely extract a module from a monolith?

Establish verification before editing, preserve the public interface and failure behavior, and extract in small steps that each keep the codebase buildable. Stop only when behavior matches the pre-change proof and the target structure is achieved.

What should stay unchanged during a behavior-preserving refactor?

Public interfaces, failure behavior, ordering, and compatibility must remain unchanged unless explicitly scoped. Dependency or configuration growth should also be avoided unless there is a correctness need.

When should I not use a behavior-preserving refactoring approach?

Avoid it when the goal is an intentional behavior change or feature addition, since mixing feature work into a refactor breaks the verification boundary. In those cases, separate the behavior change into its own reviewed change.

Why do refactors introduce regressions even when tests pass?

Regressions slip in when verification is not run identically before and after edits, or when multiple ownership boundaries move at once. Bracketing each structural edit with the same proof and keeping steps small isolates the cause of any mismatch.