skills.rest
LorenFrankLab
LorenFrankLabOFFICIAL
Explore all skills by this author →
WebsiteGitHub

safe-refactoring

Refactor code structure while preserving behavior via baseline tests and numerical equivalence.

3|1|Updated Jun 7, 2023
Search Tags:#code quality#testing#development workflow#refactoring#python#regression prevention#software maintenance
One-click install
npx skills add https://github.com/LorenFrankLab/non_local_detector --skill safe-refactoring
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: safe-refactoring
Source: https://github.com/LorenFrankLab/non_local_detector/tree/main/.claude/skills/safe-refactoring
Command: npx skills add https://github.com/LorenFrankLab/non_local_detector --skill safe-refactoring

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pytest, ruff, black.

What problem does it solve?

Refactoring code is essential for maintainability but often introduces unintended bugs or changes in behavior, leading to costly regressions. This Skill provides a strict, zero-tolerance process to ensure that structural code changes never alter functionality, allowing you to improve code quality with complete confidence.

Core Features & Use Cases

  • Behavioral Baseline: Establish a comprehensive baseline of test results, snapshot outputs, and code coverage before any changes.
  • Zero-Tolerance Verification: Rigorously compare post-refactoring results against the baseline, immediately flagging any deviation.
  • Quality Checks: Integrate linting and formatting to ensure refactoring also improves code quality standards.
  • Numerical Equivalence: For mathematical code, verify that refactoring introduces no numerical differences beyond floating-point noise.
  • Use Case: You need to reorganize a large, monolithic Python module into smaller, more focused files to improve readability and maintainability. Use this Skill to perform the refactoring, guaranteeing that all existing functionality remains perfectly intact and no new bugs are introduced.

Quick Start

Follow the safe refactoring checklist:

1. Run full test suite (establish baseline)

2. Run snapshot tests (establish baseline)

3. Capture coverage report

4. Perform refactoring (small, incremental changes)

5. Run full test suite (must match baseline exactly)

6. Run snapshot tests (must match baseline exactly)

7. Compare coverage (should stay same or improve)

8. Run quality checks (ruff + black)

9. Verify no numerical differences (for mathematical code)

10. Commit refactoring

Frequently Asked Questions about safe-refactoring

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

FAQPage Schema
How do I refactor Python code without introducing bugs?▼

Refactoring Python code safely requires establishing a behavioral baseline—running your full test suite, snapshot tests, and capturing coverage before making changes—then comparing results after refactoring to catch any deviations immediately. This zero-tolerance verification ensures structural changes never alter functionality.

What's the best way to reorganize a large Python module into smaller files?▼

Break the module into focused files incrementally, running your test suite after each change to verify behavior remains identical. Use snapshot tests to catch output changes, compare coverage to ensure it stays consistent or improves, and run ruff and black to maintain code quality throughout the reorganization.

Can I refactor mathematical code without changing numerical results?▼

Yes. After refactoring, verify numerical equivalence by comparing results against your baseline—flagging any differences beyond floating-point noise. Combined with your test suite and snapshot verification, this confirms refactoring preserves mathematical precision.

Why do refactoring projects introduce regressions?▼

Structural changes often alter behavior subtly without tests to catch them. A comprehensive baseline approach—capturing test results, snapshots, and coverage before refactoring, then verifying they match exactly afterward—eliminates regressions by detecting any deviation immediately.

Do I need pytest, ruff, and black to refactor safely?▼

These tools work together to enforce safe refactoring: pytest runs your behavioral baseline and post-refactoring tests, ruff and black enforce code quality standards during changes, and snapshot testing captures exact outputs to detect unintended behavior shifts.

What should I check after refactoring to ensure nothing broke?▼

Run your full test suite to confirm baseline results match exactly, verify snapshot tests haven't changed, compare code coverage to ensure it stayed the same or improved, run ruff and black for quality checks, and for mathematical code, validate numerical equivalence against floating-point tolerances.

Related Skills

Explore More Software Engineering Skills→
EstomEstom

python-pro

Generate type-safe async Python 3.11+ code with pytest suites and mypy --strict compliance.

Community
Advanced
abhishekmmgnabhishekmmgn

canary

Monitor live app behavior against pre-deploy baselines to detect errors and regressions.

Community
Advanced
kartikfedkartikfed

python-quality

Run Black, Ruff, Mypy, and Pytest checks on Python code.

Community
Intermediate
DmitriyYukhanovDmitriyYukhanov
6

python-coder

Implement Python code with PEP 8, type hints, and docstrings.

Community
Intermediate