Skip to content
Merged
Show file tree
Hide file tree
Changes from 30 commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
8659b57
empty
fzyzcjy Apr 6, 2026
e23d43d
abs import
fzyzcjy Apr 6, 2026
d3fc26e
mechanically move
fzyzcjy Apr 6, 2026
981710b
import
fzyzcjy Apr 6, 2026
3943b37
fmt
fzyzcjy Apr 6, 2026
ade062d
mv and rename
fzyzcjy Apr 6, 2026
6302d20
extract
fzyzcjy Apr 6, 2026
fb84c33
more
fzyzcjy Apr 6, 2026
6a06221
fmt
fzyzcjy Apr 6, 2026
f0bdf5a
more
fzyzcjy Apr 6, 2026
5e03bbe
extract
fzyzcjy Apr 6, 2026
e14676e
more
fzyzcjy Apr 6, 2026
8ee59cd
fmt
fzyzcjy Apr 6, 2026
6884a2e
add mechanical-refactor-verify skill
fzyzcjy Apr 6, 2026
6352440
keep worktree after verification for inspection
fzyzcjy Apr 6, 2026
6313761
extract scaffold into utils.py, transform script only defines transfo…
fzyzcjy Apr 6, 2026
a07fe93
rename utils.py to mechanical_refactor_verify_utils.py
fzyzcjy Apr 6, 2026
3ea792a
fix py3.10 compat: type alias and Optional syntax
fzyzcjy Apr 6, 2026
55d8d03
simplify docstring: point to SKILL.md for usage
fzyzcjy Apr 6, 2026
3666739
rename _run to exec_command
fzyzcjy Apr 6, 2026
167d5f3
replace MechanicalVerifier class with verify_mechanical_refactor func…
fzyzcjy Apr 6, 2026
704d0fe
remove RunFn, transform calls exec_command directly
fzyzcjy Apr 6, 2026
b0406a0
add git_add_and_commit helper
fzyzcjy Apr 6, 2026
f581104
move ruff format step into verify_mechanical_refactor
fzyzcjy Apr 6, 2026
85ba9a6
rename root to dir_root, remove run param from transform
fzyzcjy Apr 6, 2026
40d6eef
add gist update command, one gist per PR
fzyzcjy Apr 6, 2026
597749e
clarify PR scope: mechanical only, semantic changes go to separate PR
fzyzcjy Apr 6, 2026
2010083
remove relationship to existing refactor workflows section
fzyzcjy Apr 6, 2026
f5bf690
cp
fzyzcjy Apr 6, 2026
118423b
Merge branch 'rollout_ft/0' into rollout_ft/1
fzyzcjy Apr 6, 2026
6df2223
add mechanical refactor transform script for rollout.py split
fzyzcjy Apr 6, 2026
079635f
Revert "add mechanical refactor transform script for rollout.py split"
fzyzcjy Apr 6, 2026
40355dc
clarify: write transform to /tmp, delete after gist upload, never wri…
fzyzcjy Apr 6, 2026
73f4e6b
make verify_mechanical_refactor usage mandatory, forbid hand-rolled s…
fzyzcjy Apr 6, 2026
f9c13ac
add dedent() util, fix shlex.quote in git_add_and_commit
fzyzcjy Apr 6, 2026
ec850e5
remove __pycache__ from tracking
fzyzcjy Apr 6, 2026
f8a9af5
fix py3.10 compat: Optional[str] and add missing import
fzyzcjy Apr 6, 2026
df42bc4
more
fzyzcjy Apr 6, 2026
8d545e1
cp
fzyzcjy Apr 6, 2026
a3fe2f6
Merge branch 'rollout_ft/0' into rollout_ft/1
fzyzcjy Apr 6, 2026
21e7532
use pre-commit instead of ruff format in verify scaffold
fzyzcjy Apr 6, 2026
a352b0c
remove __pycache__
fzyzcjy Apr 6, 2026
3f32106
fmt
fzyzcjy Apr 6, 2026
ee35f3a
cp
fzyzcjy Apr 6, 2026
3d594ee
Merge branch 'rollout_ft/0' into rollout_ft/1
fzyzcjy Apr 6, 2026
b42aa4e
skip pre-commit commit when no files changed
fzyzcjy Apr 6, 2026
1fb7e93
skip pre-commit commit when no files changed
fzyzcjy Apr 6, 2026
badc784
Merge branch 'rollout_ft/0' into rollout_ft/1
fzyzcjy Apr 6, 2026
9a5e5b1
Merge main into rollout_ft/1 (cascade start)
fzyzcjy May 5, 2026
8128e97
Merge main into rollout_ft/1
fzyzcjy May 6, 2026
1ea7392
Merge origin/main into rollout_ft/1
fzyzcjy May 7, 2026
2eb8521
Merge main into rollout_ft/1
fzyzcjy May 29, 2026
17b38a8
Apply pre-commit fixes (ruff, black) to scripts/run_qwen3_4b_npu.py
fzyzcjy May 29, 2026
05444e8
Merge main into rollout_ft/1
fzyzcjy May 30, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions .claude/skills/mechanical-refactor-verify/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
---
name: mechanical-refactor-verify
description: 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.
user_invocable: true
argument: "[verify <pr_url_or_commit>] — verify an existing PR, or omit to see the workflow guide"
---

# 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

The scaffold (worktree creation, diff check, cleanup) lives in `utils.py` next to this skill. The transform script only needs to define the `transform()` function and call `MechanicalVerifier`.

Script template:

```python
#!/usr/bin/env python3
"""Reproducible transform for: <describe the mechanical move>

Run from the repo root: python3 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

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: Split source file ---
source = dir_root / "path/to/source.py"
content = source.read_text()
lines = content.splitlines(keepends=True)

splits = [
("path/to/pkg/target_a.py", 1, 50),
("path/to/pkg/target_b.py", 51, 120),
]
for target_path, start, end in splits:
target = dir_root / target_path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text("".join(lines[start - 1 : end]))

source.unlink()
(dir_root / "path/to/pkg/__init__.py").touch()

git_add_and_commit("mechanical: split source.py", cwd=str(dir_root))

# --- Step 2: Fix imports ---
# <edit files>
# git_add_and_commit("fix imports", cwd=str(dir_root))

# Note: formatting (ruff format) is handled automatically by verify_mechanical_refactor


if __name__ == "__main__":
verify_mechanical_refactor(
base_commit=BASE_COMMIT,
target_commit=TARGET_COMMIT,
transform=transform,
)
```

The `transform()` function:
- Receives `dir_root` (worktree path, checked out at base commit)
- Makes file changes and commits each logical step
- The verifier handles worktree creation, diffing against target, and reporting pass/fail

### Step 2: Run locally to verify

```bash
python3 transform.py
# Expected: "PASS: transform reproduces the commit exactly."
```

### Step 3: Upload gist and add to PR description

One gist per PR. Create or update:

```bash
# First time
gh gist create --public -d "Mechanical refactor transform: <description>" transform.py

# Update existing gist (e.g. after revising the transform)
gh gist edit <gist_id> -a transform.py
```

PR description format:

````markdown
## Mechanical Move

Transform script: <gist_url>

### One-click verification

```bash
python3 <(curl -sL <gist_raw_url>)
```
````

Anyone verifying the PR just copy-pastes the one-liner.

### Step 4: PR scope

A mechanical refactor PR should contain **only** mechanical changes (moves, splits, renames, import fixes, formatting). All of these should 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 in the repo
3. Report: PASS or show the diff
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
"""Utilities for mechanical refactor verification scripts.

See SKILL.md for usage and transform script template.
"""

import subprocess
import sys
import tempfile
from collections.abc import Callable
from pathlib import Path
from typing import Optional


def exec_command(cmd: str, cwd: Optional[str] = None, check: bool = True) -> str:
print(f" $ {cmd}", flush=True)
result = subprocess.run(
cmd, shell=True, cwd=cwd, capture_output=True, text=True,
)
if check and result.returncode != 0:
print(f"FAILED: {result.stderr}", file=sys.stderr)
sys.exit(1)
return result.stdout.strip()


def git_add_and_commit(message: str, cwd: str) -> None:
exec_command(f"git add -A && git commit -m '{message}'", cwd=cwd)


def verify_mechanical_refactor(
base_commit: str,
target_commit: str,
transform: "Callable[[Path], None]",
) -> None:
repo_root = exec_command("git rev-parse --show-toplevel")
worktree_dir = tempfile.mkdtemp(prefix="verify-mechanical-")
branch_name = f"verify-mechanical-{base_commit[:8]}"

try:
print(f"[1/4] Creating worktree at {base_commit[:8]}...")
exec_command(
f"git worktree add -b {branch_name} {worktree_dir} {base_commit}",
cwd=repo_root,
)

print("[2/4] Running transformation...")
transform(Path(worktree_dir))

print("[3/4] Formatting...")
exec_command("ruff format .", cwd=worktree_dir)
git_add_and_commit("fmt", cwd=worktree_dir)

print(f"[4/4] Diffing against {target_commit[:8]}...")
diff = exec_command(
f"git diff {target_commit} -- .",
cwd=worktree_dir,
check=False,
)

if diff:
print(f"\nFAIL: diff is non-empty:\n{diff}")
sys.exit(1)
else:
print("\nPASS: transform reproduces the commit exactly.")

finally:
print(f"\nWorktree left at: {worktree_dir}")
print(f"Branch: {branch_name}")
print("To clean up manually:")
print(f" git worktree remove {worktree_dir} && git branch -D {branch_name}")
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -192,4 +192,3 @@ glm/
_examples_synced/
.env
.DS_Store
.claude/
Loading
Loading