---
name: bulk-refactor-workflow
description: 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"