code-refactoring

name	code-refactoring
description	Orchestrate large structural code refactors combining semantic search (ast-grep) with AST-based transformation (gritql). Use for multi-file renames, API migrations, and pattern modernization with mandatory quality gates.
allowed-tools	Bash(sg *),Read,Grep,Edit,Write

Code Refactoring

Orchestrate large structural refactors using ast-grep to discover scope and gritql to apply transformations safely.

When to Use

Use this skill for:

• Multi-file refactoring (rename classes, methods, variables)
• API migrations (framework updates, library changes)
• Pattern refactoring (inheritance → composition)
• Code modernization (language idioms, best practices)

Don't use for:

• Single-file simple changes → Use Edit tool directly
• Logic changes requiring context → Manual review
• Non-code files (YAML, JSON, MD) → Use Edit tool

Workflow

1. Pre-Flight Checks

git status          # Must be clean
git checkout -b refactor/<description>

Run baseline build + tests before starting.

2. Discover Scope with ast-grep

Before transforming anything, understand the full impact:

# Find all sites that will be affected
sg --pattern '$obj.oldMethod($$$)' --lang java src/

# Verify count and locations are expected

See code-ast-grep skill for full pattern syntax.

3. Preview with gritql (MANDATORY)

grit apply '<pattern>' --dry-run > /tmp/preview.diff
# Review ALL changes before applying

See code-gritql skill for transformation pattern syntax.

4. Apply and Verify (MANDATORY)

grit apply '<pattern>'

# Format
./gradlew spotlessApply  # or equivalent formatter

# Compile
./gradlew compileJava compileKotlin

# Full test suite
./gradlew test testIntegration

# Review diff
git diff HEAD

5. Commit

git add -u
git commit -m "refactor: <clear description>"

Quality Gates

Before completing any refactor:

• ast-grep scope review done before applying
• Dry-run previewed and all changes intentional
• Code formatted
• Clean build (no compilation errors)
• Tests passing
• Git diff reviewed

Tool Selection

Scenario	Tool
Find all affected code sites	ast-grep (sg)
Multi-file expression-level Kotlin rewrite	gritql
Kotlin catch/if/try block transformation	Edit (or ast-grep --rewrite YAML)
Multi-file structural transformation (non-Kotlin)	gritql
Single file, simple change	Edit
Same text change across files	MultiEdit

Kotlin-specific note

GritQL only handles expression-level Kotlin patterns (function calls, method chains, imports). For statement-level changes — catch blocks, if statements, variable declarations, try/finally — use Edit for targeted changes or ast-grep with a YAML rule for structural multi-file rewrites. See code-gritql skill for the full Kotlin limitations list.

Progressive Context

• For transformation patterns (rename, import, annotation migration): see code-gritql skill and reference.md
• For search patterns (finding callers, usages, class definitions): see code-ast-grep skill

---

Related Skills

Skill	When to apply
code-ast-grep	Discover scope of changes before applying any transformation
code-gritql	Apply AST-based multi-file code transformations
code-architecture-best-practices	Validate refactored structure against SOLID/Clean Architecture
code-review	Verify refactor output before merging to main branch
code-debugging	Diagnose test failures or build errors introduced during refactoring