/refactor

description: Refactors code toward project-guideline compliance and testability (so /optimus:unit-test can safely increase coverage) across four analysis lenses, fanned out to parallel agents when the scope warrants it. Supports "testability" or "guidelines" focus plus flexible scoping. Read-only until the user approves the plan; applied changes stay local. Use after /optimus:init, before /optimus:unit-test, or for an iterative loop /optimus:deep refactor.
disable-model-invocation: true
argument-hint: "[testability|guidelines] [scope]"

Project-Wide Code Refactoring

Analyze existing source code against the project's own guidelines across four lenses — inline for a small scope, fanned out to parallel agents otherwise — present a prioritized refactoring plan, then apply only user-approved changes with test verification. Two goals:

1. **Guideline compliance** — align code with coding-guidelines.md, architecture.md, styling.md, and testing.md 2. **Testability** — restructure code so `/optimus:unit-test` can safely increase coverage without risky refactoring

Step 1: Prerequisites and scope

If the current directory has no `.git/` directory, read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it. In a multi-repo workspace, load each targeted repo's `.claude/CLAUDE.md` and `.claude/docs/` (not the workspace root's) and apply that repo's context to its files; if the scope doesn't determine a repo, ask which one.

If `.claude/CLAUDE.md` or `.claude/docs/coding-guidelines.md` is missing, recommend `/optimus:init` first. On the user's choice to continue, fall back to the bundled baseline: read `$CLAUDE_PLUGIN_ROOT/skills/init/templates/docs/coding-guidelines.md` and work against it plus general best practices, and note in the report that findings are generic, not project-specific.

**Focus:** a bare `testability` or `guidelines` argument sets the focus and is consumed from the scope text — a keyword inside a quoted string is scope, not focus (`"improve testability in auth"` → no focus). If both appear, take the first and say the other needs its own pass. Everything remaining is natural-language scope.

**Scope:** if the arguments describe a scope, map it to directory paths by scanning the project structure — no question needed. Otherwise use `AskUserQuestion` (header "Scope"):

• **Full project** — all source directories (default when the user just says "refactor")
• **Directory** — specific path(s) for targeted cleanup
• **Changed since** — files modified since a commit, tag, or date

For changed-since, use `git diff --name-only <ref>...HEAD` for commits, branches, and tags; for relative dates use `git log --no-merges --since="2 weeks ago" --format= --name-only` instead (`--since` is a `git log` flag, not `git diff`). Apply Step 3's exclusions to the result. In a monorepo with full-project scope, ask which subprojects to include (default: all).

Step 2: Harness mode

If your invocation prompt contains `HARNESS_MODE_INLINE`, you are a single iteration inside the `/optimus:deep` orchestrator: read `$CLAUDE_PLUGIN_ROOT/references/harness-mode.md` and follow its single-iteration protocol, which overrides the interactive steps — it covers progress-file reading, scope and file-list rules, agent-prompt overrides (including the Iteration Context Block on iterations 2+), and the apply/output protocol.

Refactor's deltas, which that reference defers back to this note:

• **Scope**: when `scope_files.current` is non-empty, treat it as the pre-resolved scope and derive analysis areas from its files' parent directories rather than resolving scope in Step 1; when empty, run Step 3's normal directory scan at full-project scope.
• **Focus**: take the finding-cap allocation from `config.focus` (empty string = balanced).
• **No PR/MR block**: the PR/MR context block does not apply to refactor — ignore `config.pr_description`.

If `HARNESS_MODE_INLINE` is not present, continue with the interactive flow below.

Step 3: Load project context and map analysis areas

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md` and load the docs it lists, applying its skill-authoring lens, its monorepo scoping rule, and its submodule exclusion. These docs define the rules: every suggestion must be justified by what they establish — never impose external preferences.

Within the scope, identify source directories. Skip non-source directories (dependencies, build output, framework caches, dot-directories), minified/lock/binary files, and the generated source files listed under "All Agents Exclude" in `$CLAUDE_PLUGIN_ROOT/references/shared-agent-constraints.md`. Group areas by top-level source directory (monorepo: by subproject, then directory) and rank by recent churn:

git log --no-merges --since="3 months" --format= --name-only -- <scope-path> | sort | uniq -c | sort -rn

Analyze highest-churn areas first; for full-project scope on a large codebase, start with the top 10. Briefly summarize docs loaded (and any missing, with fallback status), project type, and ranked areas, then proceed immediately — do not wait for confirmation.

Step 4: Four-lens analysis

The four lenses below must all be covered. Size the fan-out to the scope: **for a handful of files, analyze them yourself in one pass** — four subagents over three files each re-read CLAUDE.md and the guideline docs to reach findings you can reach directly. Fan out for a directory or wider, where the lenses genuinely read different parts of the tree.

When you do fan out, launch all 4 agents as `general-purpose` Agent tool calls in a **single** message so they run in parallel — separate messages serialize them for no benefit.

| Agent | Prompt file | Finds | |---|---|---| | 1 — Guideline Compliance | `agents/guideline-reviewer.md` | Explicit doc violations with exact rule citations | | 2 — Testability Analyzer | `agents/testability-analyzer.md` | Structural barriers to unit testing | |