refactor-workflow

name	refactor-workflow
description	Systematic code refactoring methodology using ast-grep, comby, and manual transformations. Load when performing large-scale code restructuring or systematic transformations.

Refactoring Workflow

Methodology for safe, systematic code transformation.

Phase 1: Assessment

Before touching code:

1. Scope: what needs to change and why
2. Impact: use grep and glob to find all affected files, functions, dependencies
3. Dependencies: map how the code is interconnected
4. Risk: identify high-risk areas (public APIs, concurrent code, security paths)
5. Success criteria: tests pass, lint clean, behavior preserved

Phase 2: Strategy

Choose the right tool:

ast-grep — structural, pattern-based transformations:

• Renaming variables, functions, classes across codebase
• Changing method signatures consistently
• Language-aware pattern matching and replacement
• Use sg scan to preview, sg run --rewrite to apply

comby — syntactic, template-based transformations:

• Multi-line pattern matching
• Template-driven replacements: :[[identifier]] for captures
• Language-agnostic when appropriate
• Preview with comby -match-only, apply with comby -i

Manual (edit tool) — when transforms require judgment:

• Context-dependent changes that tools can't express
• Changes requiring understanding of business logic
• Small, isolated modifications

Phase 3: Execution

Iterate in small, verifiable chunks:

1. Make ONE logical change
2. Apply the transformation
3. Verify immediately (lint, compile, test)
4. Commit progress
5. Repeat

Phase 4: Verification

1. Full test suite — catch regressions
2. Static analysis — lint, type-check
3. Behavioral verification — confirm no unintended changes
4. Review the full diff — ensure changes match intent

<risk_tiers> High risk (extra caution required):

• Public APIs / exported functions
• Core data structures
• Concurrent / async code
• Security-sensitive paths
• Configuration / deployment code

Medium risk:

• Internal APIs with multiple callers
• Shared utility functions
• Test infrastructure

Low risk:

• Internal implementation details with few callers
• Formatting / style changes
• Documentation updates </risk_tiers>

- Understand codebase structure before beginning any refactoring - Verify every change, even those that seem simple - Keep refactoring and feature work in separate commits - Leave the codebase in a working state after every step - Correctness over speed — always