packages/shared-skills/skills/refactor/SKILL.md
export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
``` /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 ```
Performs intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:
BEFORE ANY ACTION, classify and validate the request.
| 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?" |
Before proceeding, confirm:
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:
My recommendation: [suggestion with reasoning]
Should I proceed with [recommendation], or would you prefer differently? ```
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"} ]) ```
Mark phase-1 as in_progress.
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." ) ```
While background agents are running, use direct tools:
```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 ```
```typescript // Find structural patterns ast_grep_search( pattern="function $NAME($$$) { $$$ }", // or relevant pattern lang="typescript", // or relevant language paths=["src/"] )
// Preview refactoring (DRY RUN) ast_grep_replace( pattern="[old_pattern]", rewrite="[new_pattern]", lang="[language]", dryRun=true // ALWAYS preview first ) ```
``` grep(pattern="[search_term]", path="src/", include="*.ts") ```
``` background_output(task_id="[agent_1_id]") background_output(task_id="[agent_2_id]") ... ```
Mark phase-1 as completed after all results collected.
Mark phase-2 as in_progress.
Based on Phase 1 results, build:
```
``` [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) ```
| 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 |
Based on codemap:
Mark phase-2 as completed.
Mark phase-3 as in_progress.
```bash
cat package.json | jq '.scripts | keys[] | select(test("test"))'
ls -la pytest.ini pyproject.toml setup.cfg
ls -la *_test.go ```
``` // 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]:
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:
Which approach do you prefer? ```
```
After each refactoring step:
Mark phase-3 as completed.
Mark phase-4 as in_progress.
``` Task( subagent_type="plan", prompt="Create a detailed refactoring plan:
[User's original request]
[Insert codemap here]
[Insert verification plan here]
After receiving plan from Plan agent:
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"}, {"id": "verify-1", "content": "Verify Step 1: run tests", "status": "pending", "priority": "high"}, {"id": "refactor-2", "content": "Step 2: [description]", "status": "pending", "priority": "medium"}, {"id": "verify-2", "content": "Verify Step 2: run tests", "status": "pending", "priority": "medium"}, // ... continue for all steps ]) ```
Mark phase-4 as completed.
Mark phase-5 as in_progress.
For EACH refactoring step:
Use appropriate tool:
For Symbol Renames: ```typescript lsp_prepare_rename(filePath, line, character) // Validate rename is possible lsp_rename(filePath, line, character, newName) // Execute rename ```
For Pattern Transformations: ```typescript // Preview first ast_grep_replace(pattern, rewrite, lang, dryRun=true)
// If preview looks good, execute ast_grep_replace(pattern, rewrite, lang, dryRun=false) ```
For Structural Changes: ```typescript // Use Edit tool for precise changes edit(filePath, oldString, newString) ```
```typescript // 1. Check diagnostics lsp_diagnostics(filePath) // Must be clean or same as baseline
// 2. Run tests bash("bun test") // Or appropriate test command
// 3. Type check bash("tsc --noEmit") // Or appropriate type check ```
If ANY verification fails:
NEVER proceed to next step with broken tests.
After each logical group of changes:
```bash git add [changed-files] git commit -m "refactor(scope): description
[details of what was changed and why]" ```
Mark phase-5 as completed when all refactoring steps done.
Mark phase-6 as in_progress.
```bash
bun test # or npm test, pytest, go test, etc. ```
```bash
tsc --noEmit # or equivalent ```
```bash
eslint . # or equivalent ```
```bash
bun run build # or npm run build, etc. ```
```typescript // Check all changed files for (file of changedFiles) { lsp_diagnostics(file) // Must all be clean } ```
```markdown
All existing tests pass. No new errors introduced. ```
Mark phase-6 as completed.
If any of these occur, STOP and consult user:
You already know these tools. Use them intelligently:
Leverage LSP tools for precision analysis. Key patterns:
Use `ast_grep_search` and `ast_grep_replace` for structural transformations. Critical: Always `dryRun=true` first, review, then execute.
When you encounter deprecated methods/APIs during refactoring:
Remember: Refactoring without tests is reckless. Refactoring without understanding is destructive. This command ensures you do neither.
<user-request> $ARGUMENTS </user-request> `Team mode is enabled for this session. The rules below override Phase 4-6 above. Follow this protocol instead of the in-session step-by-step execution.
When invoking the Plan agent in Phase 4.1, append this additional requirement to the prompt:
``` 7. (REQUIRED when team mode is active) Output a Team Staffing Recommendation section with these fields — missing fields fail Phase 5.0:
Classification rules the plan agent must apply to each step:
Read the Team Staffing Recommendation from Phase 4. If any required field is missing, fail here and re-request the plan with the exact missing field names. Do not proceed with a partial plan.
Then choose the path:
Record the chosen path in the TodoWrite list.
Precondition checks (fail hard if any step fails):
Team spec (`~/.omo/teams/refactor-squad/config.json`):
```json { "name": "refactor-squad", "lead": { "kind": "subagent_type", "subagent_type": "sisyphus" }, "members": [ { "kind": "category", "category": "quick", "prompt": "You handle mechanical refactoring steps (LSP rename, extract variable, inline, simple move, signature change). Use LSP tools for correctness. Apply the task description's per-step instructions verbatim — no scope expansion. After edits, run lsp_diagnostics on touched files. Report via team_send_message(teamRunId=<id>, to="lead", summary=<files touched>, body=<lsp status + diff summary>) + team_task_update(status=completed). Never run tests — the external verifier handles that. Never git add, never --continue." }, { "kind": "category", "category": "quick", "prompt": "Same contract as peer quick worker." }, { "kind": "category", "category": "unspecified-low", "prompt": "You handle logic-preserving refactors that need reasoning (extract function, restructure conditional, pattern transformation, cross-file API change). Read the task description's plan step carefully. Use ast_grep_replace with dryRun=true first, review the preview, then execute. If the step is ambiguous or would require out-of-scope changes, STOP and send team_send_message(teamRunId=<id>, to="lead", summary="UNCLEAR", body=<reason>) + team_task_update(status=pending). Same reporting contract as peer quick workers. Never run tests." }, { "kind": "category", "category": "unspecified-low", "prompt": "Same contract as peer unspecified-low worker." } ] } ```
Rationale for this composition:
Team lifecycle (one team, reused until Phase 6 cleanup):
Lead monitoring loop:
While any team task is `pending | claimed | in_progress`:
Proceed to Phase 6 only when every team task is `completed` AND every paired verifier task returned PASS.
If Phase 5 used the team path, dismantle `refactor-squad` BEFORE producing the 6.6 summary. Every exit path — success, escalation, abort — must cleanup; orphan teams poison the next session's precondition check.
The `~/.omo/teams/refactor-squad/config.json` declaration stays on disk; next session reuses it.
Append to the 6.6 summary a "Dispatch path" line and, when team path was used, team metrics (teamRunId, tasks created, verifier runs, team lifetime).