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 | | lean-agent-loop | Iterate quality gate failures (format, compile, test) with parallel agents until all pass |