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

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. The skill analyzes the target against core quality principles, plans the changes, and executes them one principle at a time.

---

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.

---

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

If specs/brownfield/ exists, read architecture-map.md, test-map.md, risk-map.md, and change-strategy.md before analyzing the target. If this is a non-trivial existing codebase and those maps do not exist, recommend /brownfield before broad refactoring. Locate target symbols via symbol-map.md (Lstart-Lend anchors); 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.
7. Deep Modules — shallow pass-through modules, speculative interfaces, or abstractions with no real hidden behavior.
8. Public Interface Testing — tests coupled to private helpers, internal call order, or mock interactions instead of observable behavior.

Only violations of these principles justify a change. Do not refactor code that complies with the principles.

Step 4 — Plan Changes with Superpowers

Invoke superpowers:writing-plans to produce a structured refactoring plan. This ensures the plan is reviewed before execution and prevents ad-hoc changes that drift from the quality principles.

Produce a written plan before touching any code:

File: src/service/extraction.py
Change: Split extract_data() into extract_raw(), validate_schema(), transform_fields()
Principle: #3 — extract_data() is 87 lines
Risk: One caller in api/routes.py — update import after split

File: src/service/extraction.py
Change: Add return type annotation to all 4 functions
Principle: #2 — return types missing
Risk: None

List every file, what will change, which principle it violates, and any known call-site impact.

Step 5 — Execute One Principle at a Time

Apply changes for one principle across all affected files. Then run the test suite. Then proceed to the next principle.

Order of execution:

1. Static typing (lowest risk, foundation for other changes)
2. Dead code removal
3. Public-interface test repairs or characterization tests
4. Function decomposition
5. Deepening modules or removing shallow pass-through abstractions
6. Module splitting (if needed)
7. Error handling
8. Self-documenting cleanup

After each principle: run tests, run lint, run type checks. If anything breaks, fix it before moving to the next principle.

When committing, follow keeping-refactors-pure: commit with HARNESS_COMMIT_KIND=refactor git commit … — the pre-commit hook then blocks any staged test/snapshot edits (a pure refactor leaves them byte-identical). Any behavioral fix discovered en route goes in a separate behavior commit.

Step 6 — Mechanical Cleanup Pass (native /simplify)

After the principle-driven refactor is complete and the suite is green (Step 5), run Claude Code's native /simplify over the refactor's changed files to catch mechanical cleanups the manual pass missed — duplicate logic that should reuse a helper, redundant branches, needless intermediate variables, altitude/efficiency tweaks. Native /simplify applies the kind of fix the harness reviewers only report, so it is genuinely additive — not a duplicate of code-reviewer, which owns the structural / SOLID / module-depth judgment /simplify does not do.

Fence it with the same behavior-preservation discipline as the rest of this skill:

1. Green precondition. Only run with a passing suite — /simplify is quality-only (it does not hunt bugs) and assumes already-correct code.
2. Scope to the diff. /simplify operates on the changed code; do not let it wander outside the refactor's target path. Reject any edit to a file the refactor did not already touch.
3. Re-verify. Re-run tests, lint, and type checks after. If /simplify turns a test red, that edit was not behavior-preserving — revert that specific change, never the test.
4. Pure-refactor commit. Commit under keeping-refactors-pure (HARNESS_COMMIT_KIND=refactor). The p

---

Content truncated.