Guides a refactor, cleanup, or restructure with the right decomposition. Use when the user asks to refactor, simplify, extract, or modernize code.
71%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./packages/shared-skills/skills/refactor/SKILL.mdexport const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
``` /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 ```
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 these todos with the session's todo tool (all pending):
```
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) 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 ```
```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
sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/ ```
``` grep(pattern="[search_term]", path="src/") // narrow to *.ts with the grep tool's file-filter parameter ```
``` 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 with the session's todo tool (each step from the plan becomes a todo, followed by its verify todo):
```
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: ```bash // Preview first sg --pattern '[pattern]' --rewrite '[rewrite]' --lang ts path/to/file.ts
// If preview looks good, execute (from the ast-grep skill's directory) python3 scripts/ast_grep_helper.py replace '[pattern]' '[rewrite]' path/to/file.ts --lang ts --apply ```
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 be clean or same as the Phase 1 baseline: zero new diagnostics } ```
```markdown
All existing tests pass. No new errors introduced. ```
Mark phase-6 as completed.
sg --pattern ... --rewrite ... --lang ...)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` skill helper or `sg` CLI for structural transformations. Critical: Always preview 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.
$ARGUMENTS `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 todo 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=, to="lead", summary=, 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 the ast-grep skill helper or sg CLI to preview structural rewrites 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=, to="lead", summary="UNCLEAR", body=) + 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 clean up; orphan teams poison the next session's precondition check.
The `.omo/teams/refactor-squad/config.json` declaration stays on disk in the project; 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).
code-yeongyu/oh-my-openagent
af161f9
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.