csh
e0b1c3ab1b
upgrade commit-message, style-cleanup, and bulk-refactor-workflow to use trigger-focused frontmatter and a shared contract structure. add a first-party skill quality test gate and register it in tests documentation.
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
---
|
|
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"
|