Refactor Safely
Plan and apply refactors using a code knowledge graph with preview, dead-code detection, and impact checks before merging.
Overview
Refactor Safely is an agent skill most often used in Ship (also Build backend, Ship review) that plans refactors via a knowledge graph with preview, apply, and change detection.
Install
npx skills add https://github.com/tirth8205/code-review-graph --skill refactor-safelyWhat is this skill?
- refactor_tool modes: suggest, dead_code, and rename with preview before apply_refactor_tool
- Safety flow: get_impact_radius, get_affected_flows, and detect_changes after apply
- find_large_functions surfaces decomposition targets from the graph
- Token rule: start with get_minimal_context and detail_level=minimal
- Target budget: complete review/debug/refactor in ≤5 tool calls and ≤800 output tokens
- ≤5 tool calls target per review/debug/refactor task
- ≤800 total output tokens when using minimal detail_level
Adoption & trust: 700 installs on skills.sh; 18.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to rename or remove code but cannot see all references or whether critical user flows will break.
Who is it for?
Solo developers with the code-review-graph toolchain who refactor regularly and want ≤5-call disciplined agent sessions.
Skip if: Greenfield prototypes with no graph indexed yet, or one-line cosmetic edits that do not need impact analysis.
When should I use this skill?
Planning or executing refactoring with refactor_tool, apply_refactor_tool, or graph safety checks.
What do I get? / Deliverables
You get a previewed refactor plan, applied graph-backed edits, and a detect_changes pass confirming impact stayed within expectations.
- Previewed rename or suggestion list
- Applied refactor with detect_changes verification
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship → review because safe refactoring is exercised when changing production-bound code under review discipline. Review subphase captures pre-merge validation, rename previews, and impact-radius checks that prevent breaking critical flows.
Where it fits
Rename a shared service method after get_minimal_context shows all call sites in the graph.
Preview rename mode output and run get_affected_flows before opening a refactor PR.
Run dead_code mode to remove unreferenced helpers discovered post-launch.
How it compares
Graph-guided refactor workflow, not a generic linter-only fix or IDE rename without dependency context.
Common Questions / FAQ
Who is refactor-safely for?
Solo and indie builders using agent-playbook-style graphs who refactor existing SaaS, API, or CLI repos before ship.
When should I use refactor-safely?
Use in Ship → review before merging large renames; in Build → backend when decomposing large functions; in Operate → iterate when removing dead code after monitoring shows safe paths.
Is refactor-safely safe to install?
Check the Security Audits panel on this page; refactors can modify many files—always use rename preview and your own tests before apply.
SKILL.md
READMESKILL.md - Refactor Safely
## Refactor Safely Use the knowledge graph to plan and execute refactoring with confidence. ### Steps 1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions. 2. Use `refactor_tool` with mode="dead_code" to find unreferenced code. 3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations. 4. Use `apply_refactor_tool` with the refactor_id to apply renames. 5. After changes, run `detect_changes` to verify the refactoring impact. ### Safety Checks - Always preview before applying (rename mode gives you an edit list). - Check `get_impact_radius` before major refactors. - Use `get_affected_flows` to ensure no critical paths are broken. - Run `find_large_functions` to identify decomposition targets. ## Token Efficiency Rules - ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool. - Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient. - Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.