safe-refactor
juliusbrussee/caveman
Restructure code while preserving behavior through bracketed verification.
What is safe-refactor?
Safe-refactor establishes a verification boundary before and after structural edits to ensure behavior is preserved. Use it for code extraction, consolidation, ownership moves, or cleanup where you need confidence that refactoring hasn't changed how the code actually works.
- Define behavior-preservation boundary before making structural changes
- Establish verification (tests, proofs) that bracket the refactoring
- Move one ownership boundary at a time to isolate changes
- Preserve public interfaces, failure behavior, ordering, and compatibility
- Keep intermediate states buildable and testable
- Avoid dependency or configuration growth without correctness need
How to install safe-refactor
npx skills add https://github.com/juliusbrussee/caveman --skill safe-refactorHow to use safe-refactor
- 1.Define the scope of the refactoring and what behavior must be preserved
- 2.Write or identify existing tests/proofs that verify current behavior
- 3.Run verification to establish baseline
- 4.Perform structural edits (extraction, consolidation, moves)
- 5.Run the same verification again to confirm behavior matches
- 6.Stop when requested structure is achieved and behavior is preserved
Use cases
- Extract a function or module while ensuring all call sites still work correctly
- Consolidate duplicated code across multiple files without changing behavior
- Move code ownership between modules or packages safely
- Reorganize class hierarchies or inheritance structures
- Clean up legacy code structure without introducing regressions
- Backend engineers refactoring large codebases
- Teams maintaining legacy systems
- Developers working on shared libraries or APIs
- Anyone restructuring code where behavior verification is critical
safe-refactor FAQ
No. Keep feature changes outside the refactor. Safe refactor is strictly about restructuring while preserving existing behavior.
Keep intermediate states buildable and testable. If a step breaks the build or tests, adjust your refactoring approach to maintain working states between changes.
Move one ownership boundary at a time. This isolates changes and makes it easier to verify that behavior is preserved at each step.
Use existing tests, proofs, or behavior checks that validate the current system. Run the same verification before and after refactoring to confirm behavior matches.
Full instructions (SKILL.md)
Source of truth, from juliusbrussee/caveman.
name: safe-refactor description: Restructure code while preserving behavior. Use for extraction, consolidation, ownership moves, or cleanup where verification must bracket structural edits.
Safe refactor
Define behavior-preservation boundary and establish verification before structural edits.
- Keep feature changes outside refactor.
- Move one ownership boundary at a time.
- Preserve public interfaces, failure behavior, ordering, and compatibility unless explicitly scoped.
- Keep intermediate states buildable and testable.
- Avoid dependency or configuration growth without correctness need.
Run same proof after change. Stop when behavior matches and requested structure is achieved.
Related skills
More from juliusbrussee/caveman and the wider catalog.
surgical-patch
Fix bugs at the narrowest responsible layer with regression proof and preserved surrounding behavior.
verify-and-stop
Prove existing work meets acceptance conditions without expanding scope.
cavecrew
Three compressed-output subagents for code location, surgical edits, and diff review—save context tokens across delegations.
caveman
Ultra-compressed communication mode that cuts output tokens while keeping technical accuracy.
context-canary
Install a per-turn canary signal to detect silent context degradation and trigger recovery when it fails.
fuck-slop
Strip AI writing fingerprints and rewrite text into its target register—academic, tweet, email, blog, anything.