dev-refactor

Code Refactoring Skill

Refactor code for better structure, naming, and patterns using language-specific expert agents.

When NOT to Use

Pre-execution check: Verify test coverage exists for the refactoring target. Refactoring without tests risks silent regressions.

Pre-flight Guards

Before executing the refactoring workflow, the agent MUST run these checks:

Guard 1: Test Coverage Check

Level: WARN Check: Verify test files exist for the refactoring target

# For target file src/module/foo.ts, check for:
# - src/module/foo.test.ts
# - src/module/foo.spec.ts
# - tests/module/foo.test.ts
# - test/module/foo.test.ts
# - __tests__/module/foo.test.ts
# For Go: foo_test.go in same package
# For Python: test_foo.py or foo_test.py

Action: [Pre-flight] WARN: No test file found for {target}. Refactoring without tests risks silent regressions. Consider writing tests first (/structured-dev-cycle).

Guard 2: Rename-Only Detection

Level: INFO Check: If the user request is purely about renaming (no structural change)

# Keyword detection in user request
keywords: rename, 이름 변경, 이름 바꿔, rename variable, rename function
# AND no structural keywords
structural_keywords: extract, split, merge, restructure, reorganize, decompose

Action: [Pre-flight] INFO: For rename-only refactoring, IDE rename (F2) or sed is faster and safer (handles all references). Proceeding with full refactoring.

Guard 3: Formatting-Only Request Detection

Level: INFO Check: If the request is about formatting or style cleanup

# Keyword detection
keywords: format, formatting, indent, indentation, 포맷, 스타일, whitespace, spacing

Action: [Pre-flight] INFO: For formatting cleanup, run the appropriate formatter (prettier, gofmt, black, rustfmt). Proceeding with full refactoring.

Guard 4: File Move Detection

Level: INFO Check: If the request is about moving files between directories

# Keyword detection
keywords: move file, move to, 파일 이동, 옮겨, relocate, reorganize files
# AND no code-level changes mentioned

Action: [Pre-flight] INFO: For file moves without code changes, use git mv via mgr-gitnerd to preserve git history.

Display Format

[Pre-flight] dev-refactor
├── Test coverage: WARN — no test file for src/utils.ts
├── Rename-only: PASS
├── Formatting-only: PASS
└── File move: PASS
Result: PROCEED WITH CAUTION (0 GATE, 1 WARN, 0 INFO)

If any GATE: block and suggest prerequisite. If any WARN: show warning, ask user to confirm. If only PASS/INFO: proceed automatically.

Parameters

Options

--lang, -l       Language (auto-detected if not specified)
                 Values: go, python, rust, kotlin, typescript, java
--focus, -f      Focus area (structure, naming, patterns, all)
--dry-run        Show proposed changes without applying
--verbose, -v    Detailed output

Workflow

0. Run pre-flight guards (MUST complete before proceeding)
1. Detect language (or use --lang)
2. Select appropriate expert agent
3. Load language-specific skill
4. Analyze code structure
5. Propose refactoring changes
6. Apply changes (if not --dry-run)

Agent Selection

Refactoring Categories

Output Format

Dry Run

[dev:refactor src/utils.go --dry-run]

┌─ Agent: lang-golang-expert (sw-engineer)
├─ Skill: go-best-practices
└─ File: src/utils.go

Analysis:

[Structure] Lines 10-45
  Issue: Function too long (35 lines)
  Suggest: Extract helper functions

[Naming] Line 12
  Issue: Abbreviation in function name
  Found: func procData()
  Suggest: func processData()

[Patterns] Lines 20-30
  Issue: Repeated error handling pattern
  Suggest: Create handleError() helper

Proposed Changes:
  1. Extract lines 15-25 into validateInput()
  2. Rename procData → processData
  3. Create handleError() helper function

No changes made (dry-run mode).
Run without --dry-run to apply changes.

Apply Changes

[dev:refactor src/utils.go]

┌─ Agent: lang-golang-expert (sw-engineer)
├─ Skill: go-best-practices
└─ File: src/utils.go

Refactoring:

[1/3] Extracting validateInput()...
  ✓ Created function at line 50
  ✓ Updated calls at lines 15, 22

[2/3] Renaming procData → processData...
  ✓ Renamed function definition
  ✓ Updated 3 call sites

[3/3] Creating handleError() helper...
  ✓ Created function at line 60
  ✓ Replaced 5 error handling blocks

Summary:
  Changes applied: 3
  Lines modified: 28
  Functions added: 2
  Functions renamed: 1

Recommendation: Run tests to verify changes.

Spec Mode (--spec)

When the --spec flag is present, refactoring is guided by the target's canonical specification:

Workflow

1. Load spec: Read .codex/specs/<agent-name>.spec.md (generated by /omcustomcodex:takeover)
   • If spec doesn't exist, run takeover first: /omcustomcodex:takeover <name>
2. Extract invariants: Parse the spec's ## Invariants section as pre-flight guard constraints
3. Refactor: Perform normal refactoring (per existing workflow)
4. Verify invariants: After refactoring, check each invariant still holds:

   [Spec Verification]
   ├── ✓ Invariant 1: {description} — PASS
   ├── ✓ Invariant 2: {description} — PASS
   └── ✗ Invariant 3: {description} — FAIL (reason)
   

5. Regenerate spec: If refactoring changed the contract, run /omcustomcodex:takeover <name> to update

When to Use

Prerequisites

• .codex/specs/<name>.spec.md must exist (or will be auto-generated via takeover)
• Target must be an agent or skill (not arbitrary code)