/refactor

name: refactor
description: "Multi-target refactoring orchestrator. Use when: cleaning up messy code/docs, simplifying code, restructuring documents, batch cleanup. Not for: new features (use feature-dev), bug fixes (use bug-fix), code understanding (use code-explore). Output: refactored code/docs + review gate."
allowed-tools: Read, Grep, Glob, Edit, Write, Bash, Skill, AskUserQuestion

Refactor — Multi-Target Refactoring Orchestrator

Trigger

• Keywords: refactor, cleanup, clean up, simplify code, restructure, tidy up, reduce complexity, batch refactor
• zh-TW: 重構, 整理, 清理, 簡化

When NOT to Use

| Scenario | Alternative | |----------|------------| | New feature development | `/feature-dev` | | Bug fix | `/bug-fix` | | Code understanding | `/code-explore` | | Doc review only | `/codex-review-doc` | | Single file simplify (known target) | `/simplify` directly | | Remove AI artifacts (known doc) | `/de-ai-flavor` directly |

Prohibited Actions

❌ git add | git commit | git push — per @rules/git-workflow.md

<budget:token_budget>150000</budget:token_budget>

Arguments

| Flag | Default | Description | |------|---------|-------------| | `--target <path>` | — | Specific file or directory (repo-relative) | | `--auto` | — | Auto-detect targets using inline metrics | | `--max-targets N` | 10 | Maximum targets per run | | `--mode reference-stability` | — | Narrow pointer-conversion pass (see § Reference-Stability Targets). Requires explicit `--target` files — repeat the flag for multiple files (`--target a.md --target b.js`, ≤ 5); incompatible with `--auto` |

Workflow

Phase 0: Target Detection → Phase 2: Incremental Refactor Loop → Phase 3: Report
(Phase 1: reserved for v2 — parallel exploration)

---

Phase 0: Target Detection & Planning

`--mode reference-stability` Branch (checked first)

When this mode is passed, Phase 0 takes this branch and **bypasses the generic pipeline below entirely** — no AI-artifact heuristic, no refactor-catalog classification, and no v2 type skip (the mode accepts any maintained text file its transformation table covers: docs, code, tests, instruction surfaces — a `*.test.js` target is valid here even though the generic path skips test files as v2). In code and test files, **only comment and documentation regions are conversion candidates**: executable strings, assertion expectations, fixtures, snapshots, generated content, and ordinary data are never touched — that is INV-005's boundary, and it is what makes skipping the behavioral gate sound (an eligible **prose-only** comment cannot change runtime behavior — tool-consumed directives and pragmas such as lint/type-checker directives or source-map metadata are *not* eligible regions, since comments can carry machine semantics; anything that could change behavior is out of this mode's reach):

1. Validate each `--target` path (same path-safety rules as below) 2. Enumerate: more than **5** files (after resolving any directory) → `[REFACTOR_BLOCKED] <target>: reference-stability accepts at most 5 enumerated files` 3. Reject `--auto`: `[REFACTOR_BLOCKED] --auto: incompatible with reference-stability` 4. Determine each file's review plane (doc vs code) for step 3 of the mode's loop 5. Proceed to § Reference-Stability Targets — never to the generic code/doc paths

`--target` Mode

1. **Validate path** (per `references/target-detection.md`):

• Reject absolute paths (starts with `/`)
• Reject `..` traversal
• Reject symlink escape (resolved path outside repo root)
• Reject non-existent files
• On rejection: `[REFACTOR_BLOCKED] <path>: <reason>`

2. **Detect file type**:

• Use extension mapping from `references/target-detection.md`
• For `.md` files: run AI artifact heuristic (scan for tool names, boilerplate, etc.; 3+ matches → `doc-ai`, else → `doc-structure`)
• v2 types (config/shell/test): log `[REFACTOR_SKIPPED] {target}: type not yet dispatched (v2)` and skip

3. **Classify refactor types** from `references/refactor-catalog.md` (R01-R09 for v1)

`--auto` Mode

1. **(Optional) Baseline**: Run `/project-audit` to capture health score 2. **Scan** repo for candidate files (code + doc) 3. **Score** each candidate:

   score = 0.40 × complexity + 0.35 × change_frequency + 0.25 × isolation

• `complexity`: `wc -l <file>` normalized 0-1
• `change_frequency`: `git log --oneline -- <file> | wc -l` normalized 0-1
• `isolation`: `1 - (import_count / max_import_count)`

4. **Sort** descending, take top `--max-targets` (default 10) 5. **Classify** each target's file type and refactor types

---

Phase 2: Incremental Refactor Loop

Process each target in priority order. Budget: max `--max-targets` targets per run.

Code Targets

FOR EACH code target:
  1. /verify fast → capture baseline exit code
     IF baseline exit ≠ 0:
       [REFACTOR_SKIPPED] {target}: baseline failing, cannot verify preservation
       CONTINUE

  2. /simplify {target}

  3. /verify fast → capture post-refactor exit code

  4. Behavioral gate (per references/behavioral-gate.md):
     IF BEHAVIOR_CHANGED (0→non-0):
       [REFACTOR_SKIPPED] {target}: behavioral regression detected
       CONTINUE
     IF NO_TESTS (all steps skipped):
       ⚠️ NO_TESTS: behavioral preservation not verified (advisory, continue)

  5. /codex-review-fast (auto-loop, max 3 rounds)
     IF still blocked:
       [REFACTOR_BLOCKED] {target}: review not passing after max rounds
       CONTINUE

  6. /precommit-fast (lint + test gate, per CLAUDE.md required flow)
     IF ⛔ FAIL:
       [REFACTOR_BLOCKED] {target}: precommit not passing
       CONTINUE

  7. Mark as committable

Doc Targets

Doc targets bypass the behavioral gate entirely — docs have no executable tests.

FOR EACH doc target:
  1. Classify: AI artifact heuristic
     IF doc-ai (3+ matches): dispatch /de-ai-flavor {target}
     ELSE (doc-structure): dispatch /doc-refactor {target}

  2. /codex-rev