refactor

What it does

The skill provides a structured, multi-phase workflow to perform intelligent refactoring. It defines commands and options to specify a refactoring target, scope, and risk strategy. It orchestrates a six-phase process: codebase analysis, codemap building, test assessment, plan generation, deterministic execution, and final verification. It uses explicit steps for discovery, dependency mapping, pattern-based transformations, and verification after each change, with mandatory diagnostics and test runs throughout.

How it works

• It accepts a refactor command with a target and optional scope and strategy.
• Phase 1: Launches multiple background explore agents to locate occurrences, dependencies, similar patterns, tests, and architecture context, while concurrently using LSP tools, AST-grep, and grep for analysis.
• Phase 2: Builds a definitive codemap from Phase 1 results, including core files, dependency graphs, impact zones, and established patterns, plus constraints to follow or avoid.
• Phase 3: Assesses tests by detecting test infrastructure, analyzing coverage, and determining a verification strategy with a decision matrix based on coverage levels.
• Phase 4: Invokes a Plan agent to generate a detailed, atomic refactoring plan and then converts it into granular todos.
• Phase 5: Executes refactoring step-by-step with pre-step checks, targeted tools (rename, pattern transformations, structural edits), and mandatory post-step verification (diagnostics, tests, type checks). Includes a rollback path on failure.
• Phase 6: Performs final verification with full test suite, type checks, lint, build verification, and a summary of changes and results.
• It enforces frequent diagnostics and test runs after each change and requires commits at logical checkpoints.

When to use it

Use when you need to perform an intelligent refactor with awareness of the codebase, dependencies, and tests, especially when aiming for a safe, verifiable transformation across a file, module, or project scope. Triggered by commands like /refactor with a target and optional scope/strategy.

What it can touch

The skill integrates with LSP tools and AST-Grep tooling to touch code through:

• LSP: LspGotoDefinition, LspFindReferences, LspDocumentSymbols, LspWorkspaceSymbols, lsp_diagnostics
• AST-Grep: scripts/ast_grep_helper.py, sg CLI tool
• Pattern and structural edits via edit helper tools, and shell commands for tests and type checks
• Git for committing at checkpoints

Caveats

• Requires explicit target and scope; ambiguity triggers clarifying prompts.
• Dependent on test coverage levels: if LOW/NONE coverage, the workflow proposes user choices and may pause.
• Relies on external agents (explore, plan, oracle, librarian) to perform specialized tasks.
• Risk of modification depends on adherence to existing patterns and constraints; must not break critical paths.