safe-refactor · git:20261101.0db12c0 · 2026-11-01 · sha256 1b9baaf2660a67a1

safe-refactor git:20261101.0db12c0A

Immutable. This exact content never changes and is served at /api/v1/blob/1b9baaf2660a67a1.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_kn65rxkm3bezeyhh/1b9baaf2660a67a13b8379b50688eba31327dd8ff426847ff99cd51e5e1e9f5c.json

Then /plugin install safe-refactor@markdownregistry-kn65rxkm3bezeyhh in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: safe-refactor
description: Restructures code in atomic behavior-preserving steps verified by characterization and regression tests. Use when refactoring code, eliminating duplication, or deepening shallow modules without changing external behavior.
---

# Safe Refactor

Restructure internal code while preserving 100% of observable external behavior at every step.

## Decision tree

1. **Are you trying to change observable business behavior and restructure code in the same step?**
   - **Yes** → Separate into two commits: complete the pure behavior-preserving refactor first, then implement the behavioral change.
   - **No** → Proceed to step 2.
2. **Do passing automated tests already cover the public seam of the code being refactored?**
   - **No** → Write **Characterization Tests** at the public seam first and confirm they pass before modifying internals.
   - **Yes** → Proceed to step 3.

## Refactoring workflow

1. **Baseline & caller check**:
   - Run `grep_search` to map every caller of the target symbol across the workspace.
   - Run the typechecker and test suite via `run_command` to confirm a green baseline.
2. **Apply one atomic transformation at a time**:
   - Inline shallow pass-through wrappers or middle-man delegates.
   - Extract duplicated logic into a single pure helper.
   - Replace boolean flag clusters with a discriminated union.
   - Move methods exhibiting Feature Envy onto the module that owns the data.
3. **Bracketed verification**:
   - Run typecheck and tests immediately after each transformation. If verification fails and cannot be fixed within 30 seconds, undo only your own edits: re-apply the previous content with `replace_file_content`, or park your changes with `git stash push -- <file>`. Never run `git checkout -- <file>` or `git checkout -- .`; both discard the user's uncommitted work, not just yours. Then take a smaller step.