Code Cleanup

Use this skill to make existing code easier to read, safer to maintain, and more consistent with the surrounding project without changing what it does.

Core Rules

• Preserve behavior. Treat bug fixes, feature changes, and public API changes as separate work unless the user explicitly includes them.
• Follow the repository's local conventions before generic style preferences. Read relevant project instructions, nearby code, package scripts, and config files before editing.
• Keep scope tight. Prefer recently changed files, staged hunks, or the specific files the user named.
• Protect user work. Inspect git status before edits and do not revert or overwrite unrelated changes.
• Validate proportionally. Run the most relevant existing tests, type checks, linters, or formatters for touched code. If a validation command is unavailable or too broad for the change, say so.
• Avoid cleanup that is only personal taste. A change should improve intent, reduce real complexity, remove duplication, or align with established project patterns.

Scope Modes

• Staged cleanup: default when staged changes exist and the user asks for pre-commit cleanup. Review git diff --cached and edit only files represented in the staged work unless the user allows propagation.
• Changed-file cleanup: use when there are no staged changes or the user asks for uncommitted work. Review git diff plus named files or recent edits.
• Targeted cleanup: use for explicit files, directories, symbols, or a commit SHA. Keep edits inside that target unless a dependency update is required.
• Full-file cleanup: use only when the user asks for a deeper pass. Keep behavior stable and validate more broadly.

State the selected scope briefly before editing when it affects risk or validation.

Workflow

1. Discover context
   • Run or inspect git status, the relevant diff, and the touched file list.
   • Identify language, framework, package manager, and available commands from files such as package.json, pyproject.toml, go.mod, Cargo.toml, Makefile, CI config, and repo docs.
   • Read nearby code to match naming, error handling, component structure, data flow, and abstraction style.
2. Screen exclusions
   • Skip generated, vendored, third-party, minified, migration-generated, or scheduled-for-deletion code.
   • Do not refactor around an active suspected bug unless the user asks to fix it first.
   • Flag high-churn or cross-branch conflicts when visible, but do not block small safe edits solely on churn.
3. Find cleanup candidates
   • Look for unclear names, avoidable nesting, duplicated logic with a shared concept, oversized functions, mixed abstraction levels, dead code, stale comments, nested ternaries, flag arguments, and error handling tangled with primary logic.
   • Note bug risks separately from cleanup opportunities. Do not silently fold bug fixes into cleanup.
4. Batch edits
   • Prefer small batches grouped by dependency chain or file proximity.
   • Start with mechanical, low-risk changes before structural extraction or cross-module movement.
   • Keep public API and exported behavior stable unless the user authorized a broader refactor.
5. Validate
   • Run focused tests for touched behavior when possible.
   • Run type checks, lint, format, or pre-commit hooks when the project already defines them and they fit the touched scope.
   • If validation fails after cleanup, inspect whether the failure is related. Fix cleanup-caused failures; report unrelated pre-existing failures clearly.
6. Report
   • Summarize what changed, what was intentionally left alone, and which validation commands ran.
   • Mention any bugs or follow-up cleanup candidates that were not addressed.

Structural quality before style

Use these questions on the changed behavior before creating another abstraction:

• Identify the existing owner of each business rule and trace its actual callers. Search for semantic duplicates and unfinished migrations, not only identical lines. Reuse that owner; do not create a parallel service, validator, retry loop or source of truth.
• Trace the blast radius through direct and dynamic consumers, persistence, configuration and deployment units. Verify the affected boundary rather than merely the edited helper.
• Remove dead code only with evidence from entrypoints, dynamic registration, public exports, generated references and external consumers. Static analyzer output alone is a lead.
• Reject speculative adapters, one-use wrappers, redundant validation and broad exception handling that hides failures. Keep validation at real trust boundaries; a fallback must preserve the explicit contract and expose failure.
• Derive expected behavior from requirements and contracts. A test that reproduces the implementation's mistake is not a regression check. For a confirmed defect, show the check failing before the fix and passing afterwards.
• Report the canonical owner, affected consumers, verified simplification and remaining uncertainty. Fewer lines alone are not evidence of better behavior.

For an entire cohort, use agentic-peer-review; for recurring structural defects, use impossible-by-design. Keep this pass proportional to the actual change.

Transformation Guide

Apply these only when they make the code easier to understand in context:

Conflict Rules

• Correctness beats clarity; clarity beats cleverness; local convention beats generic advice.
• Prefer duplication when extraction would hide simple logic or force unnecessary jumping between files.
• Prefer explicit steps over compact chains when debugging or reviewing would be harder.
• Keep an abstraction when it names a real concept, owns repeated behavior, or matches a project pattern.
• Inline an abstraction when its name merely repeats the implementation.
• If a proposed cleanup is not obviously better, leave it alone and mention it as a possible follow-up.

Validation Heuristics

• For purely mechanical edits, a focused type check, lint, or affected test can be enough.
• For structural refactors, run affected tests plus the relevant type/import checks.
• For cross-module changes, validate all known consumers and check for stale imports or circular dependencies where tooling exists.
• For hot paths, large loops, rendering code, parsers, and data transformations, avoid extraction or allocation changes unless the readability gain is worth the performance risk.
• Do not modify test assertions just to make cleanup pass. Add or adjust tests only when exposing an extracted unit or preserving behavior more directly.

Anti-Patterns

• Refactoring without understanding the current behavior.
• Mixing unrelated formatting churn into logic cleanup.
• Renaming symbols for preference rather than clarity.
• Introducing a new abstraction for one small call site.
• Removing duplication that is only coincidentally similar.
• Compacting code until the reader must mentally expand it.
• Touching unrelated files to make the diff look cleaner.
• Continuing after cleanup-caused validation failures without investigating.