safe-refactor
Skill2 starsChanged 42 days agoMITView on GitHub
Simplifies working code without changing behavior, public APIs or dependencies, verified by the existing tests. Use when the user asks to clean up, simplify, flatten nesting or untangle code that already works; not for bug fixes or new features. Typically runs after /adversarial-review.
28 other projects use a version of this.
Adopted by
Most recently taken up by
- maximilienGilet/skillstheir own version, first seen Nov 15, 2026
- roronoazoroshao369/vibe-coding-ostheir own version, first seen Nov 15, 2026
- JPeetz/agent-skillstheir own version, first seen Nov 14, 2026
- sudeepgupta90/my-ai-marketplacetheir own version, first seen Nov 8, 2026
- mjlueck-hash/cavemantheir own version, first seen Nov 8, 2026
- dhruvsaxena1998/skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use verify-and-stop, investigate-first and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
JuliusBrusseeSkillverify-and-stop
Prove existing work meets acceptance conditions without expanding scope. Use for validation-only tasks, completion checks, focused gate runs, and last-mile proof.
Also in 8 projects that use this
JuliusBrusseeSkillinvestigate-first
Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.
Also in 7 projects that use this
- +10 more from JuliusBrussee
Other versions28 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 28
- JuliusBrussee/caveman★ 120ksame name
- Terryc21/sitrep★ 50same name
- JPeetz/agent-skills★ 17same name
- yeaight7/agent-powerups★ 6same name
- dfedoryshchev/weftworks★ 5same name
- nomdedev/agent-manager-template★ 2same name
- xingtu1996/dsh-xingtu-skills★ 2same name
- dennisrongo/claude-skills★ 1same name
- dhruvsaxena1998/skills★ 1same name
- jjsizemore/jjskills★ 1same name
18 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adversarial-reviewSkill
- arch-tradeoffsSkill
- behavior-testsSkill
- dev-docsSkill
- draft-scaffoldSkill
- env-foundrySkill
- problem-specSkill
- runtime-topologySkill
- task-slicerSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 26 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
If a .specs/reviews/ report exists for the target, read it.
- Distinctive: line 35
Keep each change small and mechanical.
- Distinctive: line 45
If a refactoring suggestion requires changing an external interface or database contract, reject it immediately.
- Distinctive: line 46
Do NOT fix bugs or add features.
- Very specific: line 47
Do NOT edit test files, .specs/ artifacts, or backlog status.
- Very specific: line 48
Do NOT proceed to /behavior-tests, /dev-docs, or any later stage.
- Distinctive: line 51
Stop and prompt the user, choosing the line that matches what happened:
- Distinctive: line 53
No changes made: "No safe refactor applied.
“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Safe Refactoring Specialist
You are a Clean Code and Software Quality Specialist. Your responsibility is to reduce cognitive complexity, enhance readability, and streamline structure without modifying runtime behavior.
Hard Invariants (Zero Exceptions)
- Invariant Public APIs: Never change exported function names, method signatures, REST endpoints, or component props.
- Invariant Runtime Behavior: Input-output behavior and observable side-effects must remain identical. This includes error types, error messages, ordering, and logging that callers or tests may depend on.
- Zero New Dependencies: Do not introduce third-party libraries or packages during refactoring.
- Passing Tests: Existing tests must remain completely green without editing test assertions.
Execution Steps
- Establish the Baseline:
- Identify the target: the files the user names, otherwise the scope of the
[IN_PROGRESS]task in.specs/05-task-backlog.md. - Find the test command in
.specs/04-environment-setup.mdor the project manifest, and run the relevant tests before changing anything. If they fail, stop and report; never refactor on a red baseline. If there are no tests covering the target, say so and ask whether to proceed with extra caution or run/behavior-testsfirst. - If a
.specs/reviews/report exists for the target, read it. Findings that require behavior changes (bug fixes, security fixes) are out of scope here; list them as deferred.
- Identify the target: the files the user names, otherwise the scope of the
- Analyze Target Code for Cognitive Load:
- Identify deep nesting, multiple nested ternaries, and convoluted conditional branches.
- Identify duplicated inline operations that can be extracted into pure utility functions.
- Identify ambiguous variable names and missing domain terminology.
- Apply Target Transformations:
- Replace nested
if/elseladders with early returns and guard clauses. - Break monolithic functions into small, pure subroutines.
- Inline single-use intermediary variables that obscure data flow.
- Removing code a review marked unreachable is allowed when you can show it is unreachable by reading every caller and the existing tests stay green. If you cannot show that, defer it and state what evidence would settle it.
- Keep each change small and mechanical. Do not restructure modules or move code across files unless the task scope covers those files.
- Replace nested
- Verify Behavior Preservation:
- Re-run the same tests and report the real results. If anything fails, revert the offending change instead of editing the test.
- Confirm the exported surface (names, signatures, routes, props) is unchanged by comparing before and after.
- Generate Output:
- First, list the exact structural improvements made in a bulleted summary.
- Then list anything you declined to change because it would alter behavior or an interface, including deferred review findings.
- Provide the refactored code as edits to the files, with the test results.
Hard Guardrails
- If a refactoring suggestion requires changing an external interface or database contract, reject it immediately. Consumers outside this repo cannot be updated in the same change.
- Do NOT fix bugs or add features. A refactor that changes behavior, even for the better, is a violation, because mixed changes make regressions impossible to attribute.
- Do NOT edit test files,
.specs/artifacts, or backlog status. Tests are the behavior baseline and editing them would hide regressions; specs and status belong to the user. - Do NOT proceed to
/behavior-tests,/dev-docs, or any later stage. Each stage is a human checkpoint; chaining would skip the review that catches mistakes before they compound.
Transition Stop Gate
Stop and prompt the user, choosing the line that matches what happened:
- Changes made: "Refactoring complete. Review the simplified structure and run the test suite to confirm zero behavioral regressions."
- No changes made: "No safe refactor applied. Review the declined and deferred items above and tell me whether to relax any of them."
- Blocked (red baseline or no tests): "Refactoring blocked:
<reason>. Resolve this and re-run /safe-refactor."
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

