refactoring

name	refactoring
description	Systematic, behavior-preserving code refactoring with safety gates. Dispatches refactoring-agent. Triggers: "refactor", "clean up code", "reduce tech debt", "extract method", "rename". NOT for reactive PR feedback — use code-review for that.
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]
when_to_use	Use for proactive tech-debt reduction or structural code improvement. Pair with test-driven-development (tests-first, one-change-at-a-time).
produces	null
consumes	null
dispatch-agent	refactoring-agent

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Refactoring

Goal: Improve the structure and readability of existing code without changing its observable behavior, using systematic refactoring patterns with safety gates at every step.

Iron Law: Green Before You Refactor

Never start refactoring if tests are failing. Refactoring broken code creates two problems from one. Run the full test suite first and get it green, then refactor.

Good Example (Safe Refactoring)

Refactoring: extract calculateTax() from 45-line processOrder() function
BEFORE: npm test → 47 passing, 0 failing
Refactor: extract 12 lines into calculateTax(), update all call sites
AFTER:  npm test → 47 passing, 0 failing
Result: DONE — behavior preserved, code cleaner

Bad Example (AVOID)

Refactoring: "clean up the order processing module"
BEFORE: (didn't run tests)
Refactored: moved logic, renamed variables, fixed a bug I noticed
AFTER:  npm test → 44 passing, 3 failing
[VIOLATED: Mixed refactoring with bug fix; no baseline established]

---

Phase 1: Scope Definition

Identify what needs refactoring and why:

# Review the code to be refactored
git diff main...HEAD --stat 2>/dev/null | head -20
git log --oneline -5

# Find complexity hotspots
find . -name "*.js" -o -name "*.ts" -o -name "*.py" | \
  xargs wc -l 2>/dev/null | sort -rn | head -15

# Find code smells
grep -rn "TODO\|FIXME\|HACK\|SMELL\|DUPLICATE" \
  --include="*.js" --include="*.ts" --include="*.py" . \
  | grep -v "node_modules\|.git" | head -15

Define scope:

REFACTORING SCOPE
────────────────────────────────────────
Target files:    [list of files to refactor]
Reason:          [why this code needs improvement]
Boundaries:      [what files/modules are out of scope]
Behavior contract: [what must remain unchanged]
────────────────────────────────────────

Phase 2: Safety Baseline

This phase is a hard gate — do not proceed until tests pass.

# Run the full test suite and save results
npm test 2>&1 | tee /tmp/refactor-baseline.txt
# or:  pytest -v 2>&1 | tee /tmp/refactor-baseline.txt
# or:  go test ./... 2>&1 | tee /tmp/refactor-baseline.txt

# Extract the test count
grep -cE "pass|PASS|✓|ok " /tmp/refactor-baseline.txt 2>/dev/null || \
  tail -5 /tmp/refactor-baseline.txt

Record:

SAFETY BASELINE
────────────────────────────────────────
Tests passing:   [N]
Tests failing:   [N]  ← must be 0 to proceed
Test command:    [npm test | pytest | go test | etc.]
Baseline saved:  /tmp/refactor-baseline.txt
────────────────────────────────────────

Gate: If Tests failing > 0 → report BLOCKED. Do not proceed.

Phase 3: Smell Detection

Identify refactoring targets using the standard smell catalog:

Smell	Detection	Refactoring
Long function	> 30 lines with multiple concerns	Extract method
Duplicate code	Same logic in 2+ places	Extract and DRY
Magic numbers/strings	if (code === 42)	Extract named constant
God object	Class handling too many responsibilities	Extract class
Deep nesting	> 3 levels of if/for/try	Guard clauses, early returns
Long parameter list	> 4 parameters	Introduce parameter object
Feature envy	Method uses another class's data more than its own	Move method
Data clump	3+ params always passed together	Extract into type/struct
Dead code	Unused variables, functions, imports	Delete safely
Inconsistent naming	Mixed conventions in same module	Systematic rename

Produce:

SMELL INVENTORY
────────────────────────────────────────
[file:line] — [smell name] — [priority: P0|P1|P2]
[file:line] — [smell name] — [priority: P0|P1|P2]
────────────────────────────────────────
Total smells found: [N]

Phase 4: Dispatch refactoring-agent

Dispatch the refactoring-agent with:

• The smell inventory from Phase 3
• The target files and their current content
• The safety baseline (test command + passing count)
• Explicit constraints: "do NOT change behavior, do NOT mix bug fixes"

The agent will:

1. Execute refactorings from lowest to highest risk
2. Run tests after each change step
3. Return a REFACTORING REPORT with before/after test counts and diff summary

Handoff:

• DONE → proceed to Phase 5 verification
• DONE_WITH_CONCERNS → review concerns, proceed if only style-level (not behavior-level)
• BLOCKED → test failure during refactoring — agent will have reverted; review what went wrong

Phase 5: Verification

After the agent completes:

# Re-run the full test suite
npm test 2>&1 | tee /tmp/refactor-after.txt

# Compare to baseline
echo "Before: $(grep -cE 'pass|PASS|✓' /tmp/refactor-baseline.txt 2>/dev/null) passing"
echo "After:  $(grep -cE 'pass|PASS|✓' /tmp/refactor-after.txt 2>/dev/null) passing"

# Confirm the diff is structural, not behavioral
git diff HEAD | grep "^[+-]" | grep -v "^---\|^+++" | \
  grep -vE "^[+-][[:space:]]*$" | head -30

Verification checklist:

• Test count matches baseline (no tests added or removed)
• All tests still pass
• Diff shows structural changes only (no logic changes)
• No new files outside the defined scope were touched

Phase 6: Refactoring Report

REFACTORING COMPLETE
════════════════════════════════════════
Target:         [files/modules refactored]
Smells fixed:   [N of N found]

Changes:
  [file] — [smell] → [refactoring applied]
  [file] — [smell] → [refactoring applied]

Tests:          [N] before → [N] after (must be equal)
Behavior:       PRESERVED | CHANGES_NEEDED
Code delta:     [shorter by N lines | flatter by N indentation levels]

Skipped (out of scope or too risky):
  [file] — [reason]

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════

Save Refactoring Artifact

mkdir -p docs/superomni/executions
_BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo "unknown")
_DATE=$(date +%Y%m%d)
_REF_FILE="docs/superomni/executions/refactoring-${_BRANCH}-${_DATE}.md"
echo "Refactoring record saved to ${_REF_FILE}"