agentleFS
Linchi1997yehLinchi1997yeh/craftsman-suite/skills/safe-refactor/SKILL.md

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

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.
  • JuliusBrusseeSkill

    verify-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

  • JuliusBrusseeSkill

    investigate-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

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
  1. Very specific:

    If a .specs/reviews/ report exists for the target, read it.

    line 25
  2. Distinctive:

    Keep each change small and mechanical.

    line 35
  3. Distinctive:

    If a refactoring suggestion requires changing an external interface or database contract, reject it immediately.

    line 45
  4. Distinctive:

    Do NOT fix bugs or add features.

    line 46
  5. Very specific:

    Do NOT edit test files, .specs/ artifacts, or backlog status.

    line 47
  6. Very specific:

    Do NOT proceed to /behavior-tests, /dev-docs, or any later stage.

    line 48
  7. Distinctive:

    Stop and prompt the user, choosing the line that matches what happened:

    line 51
  8. Distinctive:

    No changes made: "No safe refactor applied.

    line 53

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

  1. Invariant Public APIs: Never change exported function names, method signatures, REST endpoints, or component props.
  2. 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.
  3. Zero New Dependencies: Do not introduce third-party libraries or packages during refactoring.
  4. Passing Tests: Existing tests must remain completely green without editing test assertions.

Execution Steps

  1. 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.md or 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-tests first.
    • 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.
  2. 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.
  3. Apply Target Transformations:
    • Replace nested if/else ladders 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.
  4. 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.
  5. 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."

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.