refactor

Refactor Skill — Quality-Driven Code Improvement

Ultracode tip: A whole-repo --sweep is a broad "scan many files, report the conclusion" task — run /effort ultracode before it for wider coverage. A targeted /refactor <path> is narrow and deterministic; leave ultracode off (/effort high) for those.

Usage

/refactor src/service/extraction.py
/refactor src/repository/
/refactor --sweep            # whole-repo entropy scan (formerly /lint-drift)
/refactor --sweep --auto-fix # sweep + auto-commit CLEANUP-class items
/refactor --mechanical       # bulk mechanical transform via specs/migrate/ (Bun Phase B)

Provide a file path or directory for a targeted refactor. Use --sweep for a whole-repo entropy scan that reports accumulated drift and routes findings back into the per-principle fix flow. Use --mechanical for a large pattern→pattern transform (port, framework swap, monorepo split) driven by specs/migrate/ mapping artifacts — not for principle-by-principle cleanup. The skill analyzes the target against core quality principles, plans the changes, and executes them one principle at a time (except --mechanical, which follows the migrate flow below).

Overview

Refactoring improves the internal structure of existing code without changing its observable behavior. No new features. No behavior changes. Every change must trace to a violation of the core quality principles.

For tiny cleanup that is obviously safe and local (for example one unused import, one typo in a comment, one lint-only change), use /vibe instead. Use /refactor when the change affects structure, module boundaries, tests, or multiple files.

Mechanical Migrate Mode (/refactor --mechanical)

For bulk faithful transforms (language port, framework upgrade call-sites, monorepo split) where the behaviour oracle is the existing suite — not a new product feature.

1. Ensure specs/migrate/ exists. If missing, copy templates from .claude/templates/migrate/ (README.md, MAPPING.md, CONSTRAINTS.tsv, CANARY.md) into specs/migrate/.
2. Draft or load MAPPING.md (and optional CONSTRAINTS.tsv). Do not fan out code until the mapping is specific enough that two independent readers would make the same mechanical choice.
3. Adversarially review the mapping (not the whole tree): spawn two independent code-reviewer instances on specs/migrate/MAPPING.md (+ CONSTRAINTS.tsv if present) with fresh context; merge with merge-review-verdicts.js --policy union if both produce verdict JSON, or require a human ack for high-risk ports. Fix mapping conflicts before any production edit.
4. Canary always: apply the transform to 3 files (or the smallest representative sample), run tests/lint/types, record results in specs/migrate/CANARY.md. A canary failure revises the mapping — do not extend a broken pattern.
5. Fan-out only after canary pass, under file ownership / ownership map when present. Prefer fix-from-diagnostics when the fan-out produces a large type/lint wall.
6. Oracle: G31 still applies — do not delete or skip tests to green the suite. Prefer dual adversarial review on large diffs (review-tier.js).
7. Semantic divergence: instruct every code-reviewer spawn to apply .claude/skills/code-gen/references/semantic-divergence.md (assert side effects, rounding, bounds, Drop/defer, placeholder constants). Record open hazards in MAPPING.md → Semantic divergence watchlist.
8. Commits: keep mapping/canary commits separate from bulk code when practical (keeping-refactors-pure when behaviour is unchanged). Prefer review-attributed subjects after dual review:

   git commit -m "$(node .claude/scripts/review-commit-msg.js --subject 'port: canary batch' --from-audit specs/reviews/adversarial-review-audit.json)"
   

This mode is not /build or /sprint. If the work needs new product behaviour, use /change or /feature instead.

Drift Sweep Mode (/refactor --sweep)

/refactor <path> fixes a targeted area. /refactor --sweep runs the whole-repo entropy scan (this absorbs the former /lint-drift skill): it reports accumulated drift and routes the findings back into the per-principle fix flow below. Entropy control for agent-generated code — as agents replicate patterns, drift accumulates.

What the sweep scans:

• Structural drift (from code-graph.json, not grep): orphan/dead files (fan_in == 0), layer-violation import directions, unstable hubs, cycles. Run /code-map first if the graph is missing or stale (stale = .claude/state/graph-dirty.jsonl non-empty — the graph-refresh Stop hook normally drains it); prefer the graph over grep. Always grep for dynamic references (getattr, registries, importlib) before declaring anything dead.
• Cross-file duplicate logic: near-identical function bodies across 3+ files → extract a shared utility. This is the sweep's unique signal (neither code-map nor a targeted refactor finds it).
• Principle violations: file/function length, missing types, bare excepts, hardcoded config. Thresholds are single-sourced in code-gen/SKILL.md (do not restate them); the length/type cases are also enforced live by the hooks — the sweep catches what predates them.
• Test-quality drift: assert-nothing tests, mocked business logic.

Sweep workflow:

1. Refresh code-graph.json (/code-map) if missing or stale.
2. Scan files changed since the last sweep (marker .claude/state/last-drift-scan.txt, a commit SHA); full scan if no marker.
3. Write specs/reviews/drift-report.md — category, file:line, suggested fix, severity (CLEANUP / REFACTOR / DEBT).
4. Route REFACTOR-class items through Steps 1–8 below (the ratchet-gated fix). With --auto-fix, CLEANUP-class items may be auto-committed — they must pass the full ratchet gate.
5. Record the new scan SHA to .claude/state/last-drift-scan.txt.

When to sweep: after every ~5 /auto iterations, before a release, or when learned-rules.md grows past ~10 rules (pattern-accumulation signal). Do not refactor code outside the current change's scope without recording it as drift first.

Steps

Step 1 — Read Quality Principles

Read .claude/skills/code-gen/SKILL.md in full. Its core quality principles are the refactoring standard. Every change planned in Step 4 must cite a specific principle.

Step 2 — Analyze Current State

Context-first (Iron Law) — REQUIRED when specs/brownfield/code-graph.json exists and is not a placeholder. Before broad source reads or unconstrained search over the target:

node .claude/scripts/context-pack.js --diff --budget 1600 "<refactor goal or target path>"
# blast radius for renames/moves (when you have a node id or path):
node .claude/skills/code-map/scripts/code_wiki.js query --graph specs/brownfield/code-graph.json --callers <id>

Read only pack read_next ranges (and skeletons + Read(offset, limit) for god files). Use task_map and caller results as the impact seed. If confidence is low / no_match, one narrow rg then re-pack — do not multi-file explore. If the graph is missing on a non-trivial codebase, recommend /brownfield before broad refactoring.

If maps exist and pack confidence is low, optionally read architecture-map.md, risk-map.md, or change-strategy.md — do not front-load every essay when the pack is high-confidence. Locate symbols via pack ranges first, then symbol-map.md (Lstart-Lend); for files flagged in skeletons/, read the .skel.md and then only the relevant symbol slice with Read(offset, limit) instead of the whole file.

Coverage preflight — REQUIRED SUB-SKILL: checking-coverage-before-change for every symbol in the target path before the first edit. COVERED symbols give you the regression oracle to run after each step; UNCOVERED symbols route to pinning-down-behavior (or sprouting-instead-of-editing) before any in-place edit.

Migration preflight — REQUIRED SUB-SKILL: checking-migration-safety if the refactor touches ORM models or schema files (e.g. renaming a model field). A behavior-preserving refactor that requires a schema migration is two deployables, not one commit.

Canvas sync preflight: if specs/design/reasons-canvas.md exists and the refactor moves, renames, splits, deletes, or creates governed source files, update the Canvas Operations and Governs sections before the refactor is considered complete. After the file movement/change, run npm run canvas-sync; a mismatch is a hard-block because a refactor must not leave the living design pointing at stale paths.

For each file in the target path:

• Architecture compliance: does the file import from a layer above it? (see layering rules in code-gen/references/architecture.md)
• Function lengths: count lines in each function. Flag any over 30 lines (the pre-write-gate hook limit).
• Type coverage: identify any any (TypeScript) or missing type hints (Python). Count unannotated parameters and return types.
• Test coverage baseline: run the test suite and record current pass/fail counts and coverage percentage.
• Dead code: identify unused imports, unreachable branches, commented-out code.
• Documentation style: identify comments that restate the code rather than explaining non-obvious decisions.

Record findings in a structured list before proceeding.

Step 3 — Identify Violations

Map each finding from Step 2 to one of the core quality principles:

1. Small Modules — file exceeds 300 lines (block) or 200 lines (warning).
2. Static Typing — any, missing annotations, untyped domain concepts.
3. Functions Under 30 Lines — function body exceeds 30 lines.
4. Explicit Error Handling — bare except, untyped catches, swallowed errors.
5. No Dead Code — unused imports, commented-out code, unreachable branches.
6. Self-Documenting — comments that restate what the code does, not why.

Content truncated.