git:20261006.526f323 to git:20261015.c0bb9cf

8 added, 92 removed. Audit A to A.

---

name: refactor

description: Use when restructuring code without changing its behavior, such as extracting a module or migrating off an API. Maps the affected code, plans the steps, and runs the tests after each change.

user-invocable: true

argument-hint: "[target file or module]"

effort: high

---

# Refactor

- ## Usage

- ```

- /oh-my-claudeagent: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

- ```

- Understand the intent, map the codebase, assess risk, plan the steps, execute with the ast-grep MCP tools, and verify after each change.

- ## PHASE 0: INTENT GATE

- Classify and validate before acting.

- | 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 | Ask "What specific improvement?" when readings would change which code moves; otherwise state your reading and proceed |

- | Ambiguous scope | Uncertain | Ask "Which modules/files?" |

- ## PHASE 1: CODEBASE ANALYSIS

- Map the target before changing it: its definitions, every caller and importer, the

- tests that exercise it, and sibling code that follows the same pattern. Search directly

- with `ast_search` and Bash; a file- or module-scope refactor needs a handful of

- searches, not subagents. Fan out to `explorer` only for a `--scope=project` change whose

- search areas are independent, one agent per area, each briefed completely in its first

- prompt.

- ## PHASE 2: BUILD CODEMAP

- Dependency graph and impact zones from Phase 1:

- ### Impact zones

- | Zone | Risk Level | Action |

- |------|------------|--------|

- | Core | HIGH | Extra verification |

- | Consumers | MEDIUM | Standard verification |

- | Edge | LOW | Quick check |

- ## PHASE 3: TEST ASSESSMENT

- Find the tests that exercise the code you are about to change and run them once for a

- green baseline. If no test would fail on a behavior change in that code, pause and

- propose characterization tests first, and refuse `--strategy=aggressive` until they

- exist.

- ## PHASE 4: PLAN GENERATION

- Write the step list yourself from the codemap: atomic steps, each independently

- verifiable, ordered by dependency, with exact file paths and how to roll each one back.

- A refactor that needs an interview or owner decisions stops here: ask the user to run

- `/oh-my-claudeagent:plan`, since a `planner` subagent runs without `AskUserQuestion`.

- ## PHASE 5: EXECUTE REFACTORING

- Per step:

- 1. **Pre-Step**: Confirm the baseline is green before touching the step's files

- 2. **Execute**: Use ast-grep MCP tools for structural replacement, or Edit for targeted changes. For a symbol rename, find every reference first (`ast_search`, or the `LSP` tool's find-references where a language server is installed), then edit each site.

- 3. **Post-Step Verification**: Run typecheck + run tests

- 4. **Record Evidence**: After each verification, call `evidence_log(evidence_type="<build|test|lint>", command="<cmd>", exit_code=<code>, output_snippet="<output>")`, choosing the type that matches the command

- 5. **Complete**: Move to the next step only when verification passes

+ Preserve behavior while restructuring the requested target. Establish scope and intent before editing; ask about materially different interpretations. Accept a file, symbol, or pattern, such as "all functions using deprecated API". Default to module scope and a safe strategy; honor `--scope=file|module|project` and `--strategy=safe|aggressive` without treating aggressive as permission to change behavior.

- If a verification fails, revert that step to get back to green, then diagnose from the recorded failure output before retrying it.

+ Map definitions, callers, imports, and tests. Run a baseline; if behavior lacks coverage, propose characterization tests before restructuring and refuse aggressive changes until that coverage exists. For project-wide investigations, delegate independent search areas only if the current role permits it. Leaf workers search directly.

- ## PHASE 6: FINAL VERIFICATION

+ Plan small, independently verifiable steps in dependency order, with file targets and a way to undo each step. Use `ast_search` for structural references and preview `ast_replace` with `dry_run` before applying. Read version-matched documentation for a requested API migration.

- Full test suite, type check, lint, build, final diagnostics. Record each with `evidence_log`, including its real exit code.

+ Run affected tests and typechecks after each step. Do not continue past a failure, suppress type errors, or weaken tests to get green. Undo only your failing step without discarding others' work, then diagnose from the recorded failure. Finish with the project's relevant build, lint, and regression checks. Record every run with `evidence_log` and its real exit code; report any unverified behavior.

- ## Critical rules

+ ## Deprecated Code & Library Migration

- A refactor preserves behavior, so never hide a behavior change to get green: no type

- suppression (`as any`, `@ts-ignore`, `@ts-expect-error`), and no deleting or weakening a

- test to make it pass. Preview structural rewrites with the ast-grep MCP tools' dry_run

- where supported, and move to the next step only when the current one verifies.

+ Do not upgrade dependencies or migrate APIs unasked. For a requested migration, consult official documentation or `oh-my-claudeagent:researcher` for the supported alternative before editing.

- ## Deprecated Code & Library Migration

+ ## Claude Code

- 1. `researcher` for recommended modern alternative

- 2. No auto-upgrade unless user requests migration

- 3. When the user requests migration, fetch the latest API docs first

+ If owner decisions require an interview, ask the user to run `/oh-my-claudeagent:plan`. Do not spawn a planner child that cannot ask the user questions.