Refactor

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

Prohibited Actions

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

budget:token_budget150000

Arguments

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-review-doc (auto-loop, max 3 rounds)
     IF still blocked:
       [REFACTOR_BLOCKED] {target}: review not passing after max rounds
       CONTINUE

  3. Mark as committable

Reference-Stability Targets (--mode reference-stability)

A narrow pointer-conversion pass, typically dispatched as the bounded adjustment for an ATTENTION_DIFFUSION / REFERENCE_DRIFT stall (@skills/codex-code-review/references/loop-diagnostics.md § Attention-Diffusion Subtypes and the Banking Sequence). Its contract is deliberately tighter than the generic doc/code paths above:

FOR EACH reference-stability target (≤ 5):
  1. Measure: count eligible bare path:line pointers (comment/doc regions only), report per file
  2. Convert: homogeneous anchor transformation only
  3. /codex-review-doc or /codex-review-fast per file type (auto-loop, max 3 rounds)
  4. Mark as converted — outer whole-change gate still owed

v2 Targets

FOR EACH v2 target (config/shell/test):
  [REFACTOR_SKIPPED] {target}: type not yet dispatched (v2)
  CONTINUE

Phase 3: Report & Handoff

Per-Target Result Table

Output per references/output-template.md:

| # | Target | Type | Action | Gate | Result |
|---|--------|------|--------|------|--------|

Delta Report (--auto only)

If Phase 0 captured /project-audit baseline:

1. Run /project-audit again
2. Compare dimension scores (before vs after)
3. Output delta table

User Handoff

Generic refactors: list committable files. Suggest /smart-commit --execute (no auto-commit per @rules/git-workflow.md).

Reference-stability mode has its own handoff — no commit suggestion. Report each target as converted with its pointer count, state that the outer whole-change gate remains owed, and return control. /smart-commit --execute may be offered only after that outer pass is noted (the banking sequence in @skills/codex-code-review/references/loop-diagnostics.md § Attention-Diffusion Subtypes and the Banking Sequence); calling converted files "committable" here would offer the commit before the pass.

Review Loop

⚠️ Per @rules/auto-loop.md: fix → re-review → ... → ✅ Pass

Verification Checklist

Generic refactors:

• All code targets passed behavioral gate (/verify fast PRESERVED)
• All targets reviewed (/codex-review-fast or /codex-review-doc)
• Skip log complete for all skipped/blocked targets
• No git add/commit/push executed

Reference-stability mode (the behavioral gate does not apply — the mode runs no /simplify):

• Eligible-pointer counts (comment/doc regions only) measured and reported per file before editing
• Every change is a homogeneous anchor conversion inside an eligible region; no executable strings, assertions, fixtures, snapshots or data touched; no unrelated edits
• Exempt content (records, review evidence, scope proofs, report formats) untouched
• Each target reviewed per its plane (/codex-review-fast or /codex-review-doc)
• No mutating git operation; no checkpoint/stash created
• Handoff states the outer whole-change gate is still owed — no commit suggestion

Examples

/refactor --target src/utils.ts           # Refactor single code file
/refactor --target docs/guide.md          # Refactor single doc file
/refactor --target src/                   # Refactor all code in directory
/refactor --auto                          # Auto-detect up to 10 targets
/refactor --auto --max-targets 5          # Auto with budget cap
/refactor --mode reference-stability --target docs/features/<feature>/2-tech-spec.md --target scripts/lib/<module>.js
                                          # Pointer conversion only; handoff reports
                                          # "converted; outer gate owed" — no commit suggestion