refactor-without-behavioral-change

Guides code refactoring that preserves observable behavior with parity evidence and narrow structural scope.

1|Updated Aug 11, 2026
One-click install
npx skills add https://github.com/0xMuluh/package-development-skills --skill refactor-without-behavioral-change-0xmuluh
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactor-without-behavioral-change
Source: https://github.com/0xMuluh/package-development-skills/tree/main/refactor-without-behavioral-change
Command: npx skills add https://github.com/0xMuluh/package-development-skills --skill refactor-without-behavioral-change-0xmuluh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Refactoring often drifts into hidden behavior changes, bundled bug fixes, or broad rewrites that are impossible to review safely. This Skill enforces a disciplined workflow where every refactor explicitly states that intended behavioral change is none, establishes behavioral coverage before editing, and keeps structural improvements separate from functional changes. ## Core Features & Use Cases - Refactor Contract and PR Template: Requires an explicit statement of the maintenance problem, structural change, preserved behavior, parity evidence, and non-goals before implementation. - Behavioral Parity Verification: Guides characterization tests, before/after comparisons of values, dimensions, names, errors, and side effects, with special caution for numerical code and S4-style dispatch. - Refactor Categories and Smell Detection: Covers extracting shared logic, removing wrappers, splitting overloaded helpers, consolidating validation, and flags "while here" scope creep as separate work. - Use Case: You notice three methods duplicating the same sample-alignment rule. Use this Skill to extract one internal helper, keep all public tests unchanged, and produce a reviewable PR proving zero behavioral change. ## Quick Start Ask the AI to refactor the duplicated logic in your module into a single helper while preserving all observable behavior and producing parity evidence.

Frequently Asked Questions about refactor-without-behavioral-change

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

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

State explicitly that intended behavioral change is none, characterize existing behavior with tests before editing, make one narrow structural change, and compare before/after outputs including values, names, errors, and side effects. Keep any discovered fixes as separate work.

What should a refactoring pull request include?▼

A refactor PR should state the maintenance problem, the structural change, intended behavioral change of none, the behavior preserved, parity evidence from tests or comparisons, and explicit non-goals such as bug fixes, API changes, or dependency updates.

When is code duplication worth deduplicating?▼

Deduplicate only when the duplicated fragments represent the same semantic rule that would always change together. If two similar-looking fragments encode different domain rules, prefer clear duplication over a false shared abstraction.

Can I fix bugs in the same PR as a refactor?▼

No. Mixing bug fixes, renames, dependency updates, or error-message improvements into a refactor hides semantic changes and makes review unsafe. Record those improvements separately and give each its own scoped PR.

How do I refactor numerical or scientific code safely?▼

Characterize key numerical values, tolerances, dimensions, names, convergence flags, and random seeds before changing structure. Do not assume algebraic equivalence guarantees identical numerical behavior; treat meaningful numerical differences as a separate functional change.

Should tests change during a pure refactor?▼

Ideally public behavioral tests remain untouched, since a strong refactor preserves observable behavior. Only adjust tests that incorrectly asserted private structure, and keep unrelated test cleanup in a separate PR.