playbook/skills/bulk-refactor-workflow/SKILL.md

name	description
bulk-refactor-workflow	Use when renaming symbols, migrating APIs, or applying safe mechanical changes across many files in the repository.

Bulk Refactor Workflow（批量重构 / 大范围修改）

Overview

Guide repository-wide mechanical edits without losing scope control or damaging unrelated work. Core principle: enumerate first, transform mechanically, verify in loops, and keep every batch auditable.

When to Use

• Rename APIs, symbols, file conventions, or repeated string patterns
• Apply scripted or structural edits across many files
• Migrate callers to a new interface where the change pattern is repeatable

When Not to Use

• One-off logic changes where no repeatable transformation exists
• Exploratory redesign or feature work that needs new architecture decisions
• Cleanup that is only formatting/lint alignment; use style-cleanup directly

Inputs

• Scope: directories, file types, include/exclude rules
• Transformation: rename, replace, codemod, scripted edit, migration strategy
• Constraints: behavior-preserving vs. compatibility window vs. staged rollout
• Verification commands: smallest useful loop plus final gate

Procedure

1. Baseline and bound the scope

   • Record git status --short.
   • Dirty worktrees are allowed.
   • Do not revert unrelated changes.
   • Mark the exact target file set before editing.
   • Run a baseline verification command so existing failures are not misattributed to the refactor.

2. Enumerate every intended hit

   • Search before editing with rg, git grep, or a structured query.
   • Separate real code hits from comments, docs, generated files, and samples.
   • Write down exclusions before running the transformation.

3. Choose the safest mechanical transform

   • Prefer deterministic transforms: codemods, scripts, structured edits, or narrow search/replace with explicit scope.
   • If compatibility matters, use a staged migration: adapt providers first, migrate callers second, remove compatibility layer last.

4. Apply in bounded batches

   • First, apply the transformation in bounded batches.
   • Verify each batch before widening scope.
   • Stop immediately if output differs from the expected hit class.

5. Verify in loops

   • Run the smallest relevant verification after each batch.
   • Re-check the hit list after edits to confirm the intended pattern is gone and unintended patterns were not introduced.

6. Finish with targeted cleanup

   • If the mechanical change leaves formatting or lint fallout, Use style-cleanup for the final formatting/lint pass.
   • Keep that cleanup scoped to the refactor set unless the user approves a wider pass.

7. Report

   • Summarize files touched, transform rules used, verification evidence, and any residual risk.

Output Contract

• Scope: files, directories, and exclusions actually used
• Transformation: exact rule or script applied
• Batches: how the work was partitioned
• Verification: commands, exit status, and what each loop proved
• Risks: remaining ambiguous areas, compatibility debt, or deferred cleanup

Success Criteria

• Every changed file belongs to the declared scope
• The transformation is reproducible and explainable
• Verification passes at both batch level and final gate
• Unrelated work in the repository is preserved

Failure Handling

• If the hit list is ambiguous, stop and refine scope before editing
• If the transform cannot be expressed mechanically, downgrade to a normal refactor plan instead of pretending it is safe bulk work
• If verification fails mid-batch, stop, inspect the smallest failing delta, and correct the transform before continuing
• If compatibility risk is higher than expected, split the migration into staged commits or phases

Guardrails

• Never run repository-wide replacement without an explicit hit review
• Never mix unrelated cleanup into the same batch
• Never hide a large-scope behavior change behind the label "mechanical refactor"