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. export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command Usage ``` /refactor [--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: Understands your intent - Analyzes what you actually want to achieve Maps the codebase - Builds a definitive codemap before touching anything Assesses risk - Evaluates test coverage and determines verification strategy Plans meticulously - Creates a detailed plan with Plan agent Executes precisely - Step-by-step refactoring with LSP and AST-grep 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: [Option A] - [implications] [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 todos: ``` TodoWrite([ {"id": "phase-1", "content": "PHASE 1: Codebase Analysis - launch parallel explore agents", "status": "pending", "priority": "high"}, {"id": "phase-2", "content": "PHASE 2: Build Codemap - map dependencies and impact zones", "status": "pending", "priority": "high"}, {"id": "phase-3", "content": "PHASE 3: Test Assessment - analyze test coverage and verification strategy", "status": "pending", "priority": "high"}, {"id": "phase-4", "content": "PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan", "status": "pending", "priority": "high"}, {"id": "phase-5", "content": "PHASE 5: Execute Refactoring - step-by-step with continuous verification", "status": "pending", "priority": "high"}, {"id": "phase-6", "content": "PHASE 6: Final Verification - full test suite and regression check", "status": "pending", "priority": "high"} ]) ``` 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) LspGotoDefinition(filePath, line, character) // Where is it defined? // Find ALL usages across workspace LspFindReferences(filePath, line, character, includeDeclaration=true) // Get file structure LspDocumentSymbols(filePath) // Hierarchical outline LspWorkspaceSymbols(filePath, 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 python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' --lang ts src/ Preview refactoring first sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/ ``` Grep for Text Patterns: ``` grep(pattern="[search_term]", path="src/", include="*.ts") ``` 1.3: Collect Background Results ``` background_output(task_id="[agent_1_id]") background_output(task_id="[agent_2_id]") ... ``` Mark phase-1 as completed after all results collected. PHASE 2: BUILD CODEMAP (DEPENDENCY MAPPING) Mark phase-2 as in_progress. 2.1: Construct Definitive Codemap Based on Phase 1 results, build: ``` CODEMAP: [TARGET] Core Files (Direct Impact) `path/to/file.ts:L10-L50` - Primary definition `path/to/file2.ts:L25` - Key usage Dependency Graph ``` [TARGET] ├── imports from: │ ├── module-a (types) │ └── module-b (utils) ├── imported by: │ ├── consumer-1.ts │ ├── consumer-2.ts │ └── consumer-3.ts └── used by: ├── handler.ts (direct call) └── service.ts (dependency injection) ``` Impact Zones Zone Risk Level Files Affected Test Coverage Core HIGH 3 files 85% covered Consumers MEDIUM 8 files 70% covered Edge LOW 2 files 50% covered Established Patterns Pattern A: [description] - used in N places Pattern B: [description] - established convention ``` 2.2: Identify Refactoring Constraints Based on codemap: MUST follow : [existing patterns identified] MUST NOT break : [critical dependencies] Safe to change : [isolated code zones] Requires migration : [breaking changes impact] Mark phase-2 as completed. PHASE 3: TEST ASSESSMENT (VERIFICATION STRATEGY) Mark phase-3 as in_progress. 3.1: Detect Test Infrastructure ```bash Check for test commands cat package.json | jq '.scripts | keys[] | select(test("test"))' Or for Python ls -la pytest.ini pyproject.toml setup.cfg Or for Go ls -la *_test.go ``` 3.2: Analyze Test Coverage ``` // Find all tests related to target call_omo_agent( subagent_type="explore", run_in_background=false, // Need this synchronously prompt="Analyze test coverage for [TARGET]: Which test files cover this code? What test cases exist? Are there integration tests? What edge cases are tested? Estimated coverage percentage?" ) ``` 3.3: Determine Verification Strategy Based on test analysis: Coverage Level Strategy HIGH (>80%) Run existing tests after each step MEDIUM (50-80%) Run tests + add safety assertions LOW (<50%) PAUSE : Propose adding tests first NONE BLOCK : Refuse aggressive refactoring If coverage is LOW or NONE, ask user: ``` Test coverage for [TARGET] is [LEVEL]. Risk Assessment : Refactoring without adequate tests is dangerous. Options: Add tests first, then refactor (RECOMMENDED) Proceed with extra caution, manual verification required Abort refactoring Which approach do you prefer? ``` 3.4: Document Verification Plan ``` VERIFICATION PLAN Test Commands Unit: `bun test` / `npm test` / `pytest` / etc. Integration: [command if exists] Type check: `tsc --noEmit` / `pyright` / etc. Verification Checkpoints After each refactoring step: lsp_diagnostics → zero new errors Run test command → all pass Type check → clean Regression Indicators [Specific test that must pass] [Behavior that must be preserved] [API contract that must not change] ``` Mark phase-3 as completed. PHASE 4: PLAN GENERATION (PLAN AGENT) Mark phase-4 as in_progress. 4.1: Invoke Plan Agent ``` Task( subagent_type="plan", prompt="Create a detailed refactoring plan: Refactoring Goal [User's original request] Codemap (from Phase 2) [Insert codemap here] Test Coverage (from Phase 3) [Insert verification plan here] Constraints MUST follow existing patterns: [list] MUST NOT break: [critical paths] MUST run tests after each step Requirements Break down into atomic refactoring steps Each step must be independently verifiable Order steps by dependency (what must happen first) Specify exact files and line ranges for each step Include rollback strategy for each step Define commit checkpoints" ) ``` 4.2: Review and Validate Plan After receiving plan from Plan agent: Verify completeness : All identified files addressed? Verify safety : Each step reversible? Verify order : Dependencies respected? Verify verification : Test commands specified? 4.3: Register Detailed Todos Convert Plan agent output into granular todos: ``` TodoWrite([ // Each step from the plan becomes a todo {"id": "refactor-1", "content": "Step 1: [description]", "status": "pending", "priority": "high"},