/refactor

name: refactor
description: "Guides a refactor, cleanup, or restructure with the right decomposition. Use when the user asks to refactor, simplify, extract, or modernize code."
argument-hint: "<refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]"

export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command

Usage

\`\`\` /refactor <refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]

Arguments: refactoring-target: What to refactor. Can be:

• File path: src/auth/handler.ts
• Symbol name: "AuthService class"
• Pattern: "all functions using deprecated API"
• Description: "extract validation logic into separate module"

Options: --scope: Refactoring scope (default: module)

• file: Single file only
• module: Module/directory scope
• project: Entire codebase

--strategy: Risk tolerance (default: safe)

• safe: Conservative, maximum test coverage required
• aggressive: Allow broader changes with adequate coverage

\`\`\`

What This Command Does

Performs intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:

1. **Understands your intent** - Analyzes what you actually want to achieve 2. **Maps the codebase** - Builds a definitive codemap before touching anything 3. **Assesses risk** - Evaluates test coverage and determines verification strategy 4. **Plans meticulously** - Creates a detailed plan with Plan agent 5. **Executes precisely** - Step-by-step refactoring with LSP and AST-grep 6. **Verifies constantly** - Runs tests after each change to ensure zero regression

---

PHASE 0: INTENT GATE (MANDATORY FIRST STEP)

**BEFORE ANY ACTION, classify and validate the request.**

Step 0.1: Parse Request Type

| Signal | Classification | Action | |--------|----------------|--------| | Specific file/symbol | Explicit | Proceed to codebase analysis | | "Refactor X to Y" | Clear transformation | Proceed to codebase analysis | | "Improve", "Clean up" | Open-ended | **MUST ask**: "What specific improvement?" | | Ambiguous scope | Uncertain | **MUST ask**: "Which modules/files?" | | Missing context | Incomplete | **MUST ask**: "What's the desired outcome?" |

Step 0.2: Validate Understanding

Before proceeding, confirm:

• [ ] Target is clearly identified
• [ ] Desired outcome is understood
• [ ] Scope is defined (file/module/project)
• [ ] Success criteria can be articulated

**If ANY of above is unclear, ASK CLARIFYING QUESTION:**

\`\`\` I want to make sure I understand the refactoring goal correctly.

**What I understood**: [interpretation] **What I'm unsure about**: [specific ambiguity]

Options I see: 1. [Option A] - [implications] 2. [Option B] - [implications]

**My recommendation**: [suggestion with reasoning]

Should I proceed with [recommendation], or would you prefer differently? \`\`\`

Step 0.3: Create Initial Todos

**IMMEDIATELY after understanding the request, create these todos with the session's todo tool (all pending):**

\`\`\`

• phase-1: PHASE 1: Codebase Analysis - launch parallel explore agents
• phase-2: PHASE 2: Build Codemap - map dependencies and impact zones
• phase-3: PHASE 3: Test Assessment - analyze test coverage and verification strategy
• phase-4: PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan
• phase-5: PHASE 5: Execute Refactoring - step-by-step with continuous verification
• phase-6: PHASE 6: Final Verification - full test suite and regression check

\`\`\`

---

PHASE 1: CODEBASE ANALYSIS (PARALLEL EXPLORATION)

**Mark phase-1 as in_progress.**

1.1: Launch Parallel Explore Agents (BACKGROUND)

Fire ALL of these simultaneously using \`call_omo_agent\`:

\`\`\` // Agent 1: Find the refactoring target call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all occurrences and definitions of [TARGET]. Report: file paths, line numbers, usage patterns." )

// Agent 2: Find related code call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all code that imports, uses, or depends on [TARGET]. Report: dependency chains, import graphs." )

// Agent 3: Find similar patterns call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find similar code patterns to [TARGET] in the codebase. Report: analogous implementations, established conventions." )

// Agent 4: Find tests call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all test files related to [TARGET]. Report: test file paths, test case names, coverage indicators." )

// Agent 5: Architecture context call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find architectural patterns and module organization around [TARGET]. Report: module boundaries, layer structure, design patterns in use." ) \`\`\`

1.2: Direct Tool Exploration (WHILE AGENTS RUN)

While background agents are running, use direct tools:

LSP Tools for Precise Analysis:

\`\`\`typescript // Find definition(s) lsp_goto_definition(filePath, line, character) // Where is it defined?

// Find ALL usages across workspace lsp_find_references(filePath, line, character, includeDeclaration=true)

// Get file structure lsp_symbols(filePath, scope="document") // Hierarchical outline lsp_symbols(filePath, scope="workspace", query="[target_symbol]") // Search by name

// Get current diagnostics lsp_diagnostics(filePath) // Errors, warnings before we start \`\`\`

AST-Grep Skill for Pattern Analysis:

\`\`\`bash // Find structural patterns — run this from the ast-grep skill's directory; this skill ships no scripts/ python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' src/ --lang ts

Preview refactoring first

sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/ \`\`\`

Grep for Text Patterns:

\`\`\` grep(pattern="[search_term]", path="src/") // narrow to *