arkazhuo/compactionrl-agent-rl/mechanical-refactor-verify

Claude Code and agent skill by arkazhuo/compactionrl-agent-rl

Trust tier 3
  • community
  • ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]
Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install arkazhuo/compactionrl-agent-rl/mechanical-refactor-verify

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

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_<short_description>.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: <describe the mechanical move>
Run from the repo root: python3 /tmp/transform_<short_description>.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 = "<base_sha>"
TARGET_COMMIT = "<pr_mechanical_move_final_sha>"
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 <repo_root>
python3 /tmp/transform_<short_description>.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: <description>" /tmp/transform_<short_description>.py
# Or update: gh gist edit <gist_id> -a /tmp/transform_<short_description>.py
# 2. Delete local file
rm /tmp/transform_<short_description>.py
# 3. Update PR description (paste the block below)

PR description must include:

`markdown
## Mechanical Move
Transform script: <gist_url>
### One-click verification

python3 <(curl -sL <gist_raw_url>)

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

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Not refreshed yet.

Extension points

  • hookPre/post lifecycle hooks

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/arkazhuo/compactionrl-agent-rl/mechanical-refactor-verify/badge)](https://verified-skill.com/skills/arkazhuo/compactionrl-agent-rl/mechanical-refactor-verify)

Something wrong with this skill or its page? Tell us.