# Mechanical Refactor Verify > Verify mechanical refactoring commits by requiring a reproducible transform script (gist) in the PR description. Use when doing or reviewing file splits, function moves, or module extractions. Use when this capability is needed. - Skill: `tomevault-io/mechanical-refactor-verify` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/mechanical-refactor-verify` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mechanical-refactor-verify/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/mechanical-refactor-verify --- # Mechanical Refactor — Reproducible Verification ## Core Principle The deliverable of a mechanical move (file split, function move, module extraction) is NOT the diff — it is **the script that produces the diff**. A script is auditable; a diff is not. ## Workflow Regardless of who did the move (human or agent) and when (before or after committing), the workflow is the same: ### Step 1: Write the transform script to /tmp/ Write the script to `/tmp/transform_.py`. **Never write it inside the repo.** The scaffold (worktree creation, diff check, ruff format, result reporting) lives in `mechanical_refactor_verify_utils.py` next to this skill. **MANDATORY**: The transform script MUST use `verify_mechanical_refactor()` from the utils module. Do NOT reimplement the verification scaffold — no hand-written worktree management, no hand-written diff checking. The script only defines `transform()` and calls `verify_mechanical_refactor`. #### Key principle: move lines, don't paste content The transform script must **read lines from the source file and write them to the target**, not hardcode large blocks of code as string literals. This is what makes the script auditable — a reviewer can verify line ranges against the original file. **Rules:** 1. **Move code by line ranges**: read the source, extract line slices, write to target. Never paste >3 lines of code as string literals in the script. 2. **Minimal replacements**: when adapting moved code (e.g. `self.foo` → `foo`), use small targeted `str.replace()` or `re.sub()` calls. Each replacement should be a short pattern, not a full block of code. 3. **New content is OK only for glue**: import statements, function signatures (the `def` line + parameters), and other 1-2 line connective tissue can be written as literals. The *body* of moved functions must come from line extraction. #### Script template (follow this structure exactly) ```python #!/usr/bin/env python3 """Reproducible transform for: Run from the repo root: python3 /tmp/transform_.py """ import sys from pathlib import Path sys.path.append(".claude/skills/mechanical-refactor-verify") from mechanical_refactor_verify_utils import verify_mechanical_refactor, exec_command, git_add_and_commit, dedent BASE_COMMIT = "" TARGET_COMMIT = "" def transform(dir_root: Path) -> None: """Perform the mechanical transformation and commit each step. Args: dir_root: Path to the worktree (checked out at BASE_COMMIT). """ # --- Step 1: Extract functions by line range --- source = dir_root / "path/to/source.py" content = source.read_text() lines = content.splitlines(keepends=True) # Move lines 100-150 to new file, dedenting from method to top-level extracted = "".join(lines[99:150]) extracted = dedent(extracted, 4) # remove class indentation # Minimal adaptations: self.x -> x (parameter) extracted = extracted.replace("self.args", "args") target = dir_root / "path/to/pkg/target.py" target.parent.mkdir(parents=True, exist_ok=True) target.write_text("import logging\n\n\n" + extracted) # --- Step 2: Remove extracted lines from source, add import --- # Delete lines 100-150 from source new_lines = lines[:99] + lines[150:] source.write_text("".join(new_lines)) # Small targeted replacement: add import, replace call site content = source.read_text() content = content.replace( "from path.to.old import foo", "from path.to.old import foo\nfrom path.to.pkg.target import extracted_func", ) # Replace inline code with function call (use a short unique anchor) content = content.replace("old_call_pattern", "new_call_pattern") source.write_text(content) git_add_and_commit("mechanical: extract functions", cwd=str(dir_root)) # Note: pre-commit run --all-files is run automatically after transform() returns if __name__ == "__main__": verify_mechanical_refactor( base_commit=BASE_COMMIT, target_commit=TARGET_COMMIT, transform=transform, ) ``` ### Step 2: Run the script from the repo root ```bash cd python3 /tmp/transform_.py # Expected: "PASS: transform reproduces the commit exactly." ``` If FAIL, fix the script and re-run until PASS. ### Step 3: Upload gist, delete local file, update PR description One gist per PR. Do all three: ```bash # 1. Create gist (or update existing) gh gist create --public -d "Mechanical refactor transform: " /tmp/transform_.py # Or update: gh gist edit -a /tmp/transform_.py # 2. Delete local file rm /tmp/transform_.py # 3. Update PR description (paste the block below) ``` PR description must include: ````markdown ## Mechanical Move Transform script: ### One-click verification ```bash python3 <(curl -sL ) ``` ```` ### Step 4: PR scope A mechanical refactor PR must contain **only** mechanical changes (moves, splits, renames, import fixes, formatting). All of these must be reproducible by the transform script. Semantic changes (new logic, API restructuring, behavior changes) belong in a **separate PR**. ## Verifying an existing PR (`/mechanical-refactor-verify verify`) 1. Find the gist URL and one-click command in the PR description 2. Run the one-click command from the repo root 3. Report: PASS or show the diff --- > Source: [radixark/miles](https://github.com/radixark/miles) — distributed by [TomeVault](https://tomevault.io).