refactoring

Restructures internal APIs and code while pinning behavior with before-and-after output comparisons.

1|Updated Sep 10, 2026
One-click install
npx skills add https://github.com/blauwtje/exo --skill refactoring-blauwtje
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refactoring
Source: https://github.com/blauwtje/exo/tree/main/skills/refactoring
Command: npx skills add https://github.com/blauwtje/exo --skill refactoring-blauwtje

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Refactors often go wrong in two ways: the old API is kept beside the new one as a shim or re-export, creating a permanent dual path, or the reshape is trusted because it type-checks while behavior silently changes. This Skill enforces a loop that pins behavior first, migrates every caller, deletes the old API in the same change, and proves equality on real outputs. ## Core Features & Use Cases - Behavior pinning: Captures current outputs in a test, snapshot, or throwaway comparison script before the first move, and reruns the pin after every step. - Caller migration and old-API deletion: Inventories every caller across source, tests, docs, and string literals, migrates them all, then deletes the old definition with a zero-hit search as evidence. - Subtraction-first reshaping: Deletes dead code and one-caller wrappers before building the new shape, and refuses seams, factories, or flags with a single implementation. - Use Case: When renaming a module and flattening its call graph, run the loop to snapshot outputs, migrate all callers, delete the old path, and quote the zero-mismatch comparison in the report. ## Quick Start Ask the AI to run the refactoring skill to rename and restructure a module while keeping its behavior unchanged.

Frequently Asked Questions about refactoring

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

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

Pin current behavior first with a test, snapshot, or throwaway script that runs old and new code over the same inputs. After each structural step, rerun the pin and count mismatches; type checks and lint passes never prove outputs stayed equal.

How to safely rename or move an internal API across a codebase?▼

Search the symbol and import path across source, tests, scripts, docs, config, and string literals, then migrate every caller before touching the old definition. Delete the old definition or re-export and search again; zero hits is the evidence the move finished.

Should I keep a backward-compatible shim after refactoring?▼

No, not for APIs whose every caller lives in the same repository; a kept shim becomes a permanent dual path. The one exception needs a named reason, an owner, and a removal date written beside it, such as an explicit user request.

When should I not use a behavior-preserving refactor workflow?▼

Avoid it when the change alters behavior, when the cause of a failure is unproven, or when persisted data, stored formats, or consumers outside the repository are involved. Those cases need phased migration or debugging instead of delete-in-place refactoring.

Why is a green test suite not enough to prove a refactor is safe?▼

A suite that never covered the moved code proves nothing, and type checks verify shapes rather than values. Only a before-and-after run over branch boundaries, enum values, and edge cases shows the outputs actually matched.