code-slimming

name	code-slimming
description	· Audit read-only code slimming: dead code, unused files, duplicate blocks, wrapper removal, commented-out code. Triggers: 'slim codebase', 'dead code', 'unused functions', 'dedupe'. Not for bugs or broad reviews.
license	MIT
compatibility	None - works on any codebase
metadata	{"source":"iuliandita/skills","date_added":"2026-05-02","effort":"medium","argument_hint":"[scope-or-diff]"}

Code Slimming: Read-Only Refactor Opportunity Audit

Find behavior-preserving opportunities to make a codebase smaller, clearer, and less repetitive. This skill reports opportunities only. It does not edit code and does not write tests.

It works on four slimming axes:

1. Dead code - unused functions, methods, variables, parameters, imports, types, exports, constants, branches, files, and dependencies that nothing reaches.
2. Redundant code - duplicate or near-duplicate blocks, whether across the repo or repeated inside a single file, including exact copy-paste clones.
3. Wrapper and indirection removal - thin layers that forward without adding a real role.
4. Comment volume - commented-out code, comments that restate the code, and banner walls that add bytes without signal. Comments should be minimal and earn their place.

The goal is not fewer lines at any cost. The goal is lower maintenance burden with behavior, performance, readability, and validation made explicit.

When to use

• Finding behavior-preserving opportunities to simplify a repository, package, module, or PR without implementing them
• Hunting dead code: unused functions, variables, imports, types, exports, unreachable branches, orphan files, and unused dependencies (Step 4 enumerates the full set)
• Auditing duplicated logic, schemas, handlers, or adapters, and redundant blocks repeated across the repo or inside a single file, including exact clones
• Trimming comment volume: commented-out code, comments that restate the code, and banner walls
• Finding safe centralization candidates before a cleanup/refactor PR, or reviewing a bot or human cleanup PR that claims to reduce code size
• Ranking maintainability refactors by value, risk, and validation needs, when the goal is smaller behavior-preserving structure rather than general cleanliness or AI-slop detection

When NOT to use

• Bug-focused reviews, regressions, races, edge cases, or crashes - use code-review
• General cleanup, naming, AI tells, dependency creep, overengineering, comment noise as a quality smell, or duplicate-code-as-slop without an explicit slimming goal - use anti-slop. (Comment lane: code-slimming deletes commented-out code, restating comments, and banner walls; anti-slop judges comment noise as a smell; anti-ai-prose rewrites AI-voiced comment text.)
• Rewriting comments or docstrings for tone and AI voice (not deleting them) - use anti-ai-prose
• Security vulnerabilities, secret scanning, auth flaws, or exploitability - use security-audit
• Writing, debugging, or adding validation tests for a slimming recommendation - use testing
• Broad quick merge checks - use full-review
• Comprehensive repo audits across all applicable dimensions - use deep-audit
• Direct implementation work - use the relevant language, framework, or domain skill

Routing boundaries

User intent	Use
"Slim this codebase", "find safe deletions", "review LOC deletion"	code-slimming
"Find dead/unused code", "unused functions/files", "remove duplicates"	code-slimming
"Delete commented-out code", "cut these comment walls down"	code-slimming
"Remove this wrapper/indirection layer", "inline this passthrough"	code-slimming
"Clean this up", "does this look AI-written?", "overengineered/verbose"	anti-slop
"These comments are noisy/AI-slop, clean them up"	anti-slop
"This prose/comments read AI-written, rewrite the voice"	anti-ai-prose
"Review this", "find bugs", "sanity check", "will this break?"	code-review
"Write/add/debug tests for this refactor"	testing
"Run all checks", "full review", "audit this repo"	full-review or deep-audit
"Implement the slimming/refactor"	Relevant language/framework/domain skill

Do not activate this skill for generic review, cleanup, or audit wording unless the user explicitly asks for slimming, deduplication, deletion, wrapper removal, or behavior-preserving size reduction.

---

AI Self-Check

Before returning a code-slimming audit, verify:

• Read-only boundary held: no source files were edited and no tests were written
• Behavior preserved: every recommendation names the behavior that must stay identical
• Value explained: every recommendation states why the slimmer shape is better
• Tradeoffs assessed: performance, coupling, readability, bundle size, allocation count, and test brittleness were considered where relevant
• Validation named: each Do now or Do with tests item lists concrete validation commands or test coverage needs
• No abstraction theater: no vague "make this generic" or "create a base class" advice without the proposed shape
• Duplication judged in context: likely divergence, framework conventions, and explicitness were considered before recommending centralization
• Defensive duplication preserved: repeated guards across trust, process, persistence, or public-API boundaries were not flagged for removal solely because an upstream layer validates the same condition
• Dead code proven, not guessed: every "unused" claim cites a no-reference search and rules out reflection, dynamic dispatch, DI, serialization, plugin/CLI/route registration, public API, conditional compilation, and test discovery before recommending deletion
• Comment trimming is deletion, not rewriting: only commented-out code, comments that restate the code, and dead banner walls are flagged; tone and AI-voice rewrites are routed to anti-ai-prose, and load-bearing comments (why, invariants, links, license, lint pragmas) are kept
• Correctness and security routed: bugs go to code-review; vulnerabilities go to security-audit
• Routing lane held: generic cleanup, slop, correctness, security, test-writing, broad-review, and implementation work were routed instead of reported as code-slimming findings
• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• Routing overlap checked: recommendations do not duplicate anti-slop, code-review, testing, full-review, or deep-audit responsibilities
• Spec claims verified: any statement about skill behavior, output contracts, or repo conventions is checked against current skill files and scripts

---

Performance

• Start with changed files, shared modules, and repeated directory shapes before scanning the whole repo.
• Group repeated examples into one finding with representative paths.
• Prefer cheap structural searches before expensive test suites.

---

Best Practices

• Treat smaller code as a hypothesis, not a win.
• Treat "unused" as a claim that must be proven by search, not assumed from local reading. A symbol with zero static references can still be live through reflection, dynamic dispatch, DI, serialization, plugin/CLI/route registration, public API, conditional compilation, or test discovery. Prove no-reference before recommending deletion.
• Keep dead-looking code that is a stable public/exported API, a documented extension point, or guarded behind a feature flag, build target, or platform; deleting these changes a contract.
• Treat commented-out code as dead code: recommend deleting it, since version control already preserves history. Keep comments that carry intent, invariants, links, license, or lint pragmas.
• Prefer deleting wrappers over adding a new abstraction layer only after proving the wrapper has no boundary, policy, observability, compatibility, or lifecycle role.
• Prefer a small well-named helper over a framework-shaped base class.
• Keep domain-specific duplication when the variants are likely to diverge.
• Keep defensive duplication when checks intentionally repeat across trust boundaries, process boundaries, public APIs, persistence layers, or privileged operations. Do not remove a repeated guard just because an upstream layer appears to validate the same condition.
• Avoid centralizing across independently versioned modules, separately owned teams, protocol or API versions, tenant-specific behavior, or plugin/provider boundaries unless the shared contract is explicit and stable.
• Recommend tests before centralization when behavior differences are subtle or undercovered.

Workflow

Step 1: Determine scope

Pick the narrowest useful scope:

• PR or diff - default when uncommitted changes or a branch diff exists
• Specific path - use when the user names files or directories
• Whole repo - use when the user asks for a repo-wide slimming audit

For git repos, gather cheap preflight context before deciding:

• repo root and branch: git rev-parse --show-toplevel, git branch --show-current
• uncommitted files: git diff --name-only, git diff --cached --name-only
• branch base when available: git merge-base HEAD @{upstream}; otherwise detect the default branch and use git merge-base HEAD origin/<default-branch>
• default branch when needed: git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null or inspect git remote show origin
• changed files and size: git diff --name-only <base>...HEAD, git diff --stat <base>...HEAD

Scope precedence:

1. User-provided diff or path
2. Uncommitted changes
3. Current branch against upstream
4. Current branch against the default branch
5. Whole repo, or ask one concise question when interactive

If the scope is unclear and no diff exists, ask one concise question. In headless contexts, default to whole repo and state the assumption.

Step 2: Gather context

Read project instructions and manifests before judging code shape:

• instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules, .windsurfrules
• manifests: package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle, CMakeLists.txt, Makefile
• test and check scripts
• existing shared modules, helper directories, framework conventions, and recent related commits

Note the language and framework patterns in the report header. A good centralization in Python may be a bad abstraction in Rust, Java, or C.

Step 3: Identify validation without over-running it

Running existing read-only validation commands is allowed unless the user forbids command execution or the commands have side effects. Separate validation into three passes:

1. Early baseline validation - cheap checks that describe current repo or diff health:
   • lint or format checks when fast and obvious
   • type or compile checks when fast and local
   • documented project validation commands
2. Candidate coverage evidence - after finding a slimming candidate, inspect existing tests, callers, snapshots, fixtures, or examples that exercise the behavior to preserve.
3. Implementation validation - commands or tests someone must run if they implement the recommendation.

Do not run expensive full suites before candidate discovery unless the user asked for PR validation or the project makes the command cheap and standard. If a check is missing, slow, flaky, noisy, unavailable, external-service-dependent, or exits zero while printing warnings, report that as a validation gap. Do not call an opportunity safe when validation is absent.

Passing current checks does not by itself make a proposed slimming safe. Do now requires behavior-specific coverage evidence, or a trivial mechanical change whose invariant is directly verifiable. Generic lint, type, and build commands alone are not enough for behavioral deduplication or centralization.

For future work, identify the validation an implementation must pass. Do not write tests in this skill.

Step 4: Search for candidates

Run the searches for all four axes. Use structural and textual searches to find:

Dead code (unused / unreachable):

• functions, methods, classes, variables, parameters, constants, types, and exports with no references anywhere in scope
• imports that are never used and dependencies in the manifest that nothing imports
• files and modules that nothing imports, requires, includes, or registers (orphans)
• unreachable code: statements after return/throw/break, if (false) branches, dead case arms, conditions that cannot be true, and feature-flag branches for removed flags
• commented-out code blocks left behind from past edits

Redundant / duplicate code:

• near-duplicate files, classes, structs, functions, methods, hooks, handlers, or components
• exact copy-paste clones repeated across files or repeated inside a single file
• repeated type, interface, schema, DTO, record, enum, or data container shapes
• repeated request parsing, query construction, pagination, validation, mapping, serialization, or error handling
• parallel provider, client, repository, service, or adapter implementations with the same skeleton
• dependencies or helpers duplicating standard library or framework features
• generated-looking copy-paste that survived human maintenance, after checking whether a generator, schema, template, or vendored source owns it

Wrappers and bloat:

• wrappers with little behavior beyond forwarding to another object or function
• oversized utils, helpers, common, shared, or misc modules
• comment walls: banner art, comments that restate the next line, and stale doc blocks

Discovery recipe:

1. Build a candidate map from changed files, same-role siblings, repeated basenames, large generic modules, and repeated exported symbols, routes, schemas, DTOs, handlers, parsers, validators, mappers, and serializers.

2. Use cheap searches before manual reading: compare same-role trees such as providers/*, clients/*, services/*, repositories/*, handlers/*, routes/*, and adapters/*; search repeated declarations and one-line wrappers that only forward to another call; find large generic modules named utils, helpers, common, shared, or misc.

3. For dead-code candidates, search for every reference to the symbol (definition site, call sites, re-exports, string-keyed lookups, config/route tables, DI registrations) before classifying it unused. Lean on the repo's own dead-code and clone tooling when present - it scopes the search and reduces both misses and false positives:

   Concern	Common language-agnostic or per-language tools
   Unused symbols/exports	knip (TS/JS; supersedes the archived ts-prune); vulture, ruff F401/F841 (Python); staticcheck, deadcode (Go); cargo dead_code warnings (Rust); compiler -Wunused (C/C++)
   Unused dependencies	knip, depcheck (JS); deptry (Python); cargo-machete (Rust)
   Copy-paste clones	jscpd (multi-language), PMD CPD (multi-language)

   Treat tool output as a candidate list, not a verdict: confirm each hit by reading, and discount known false positives (reflection, dynamic dispatch, DI, serialization, plugin/CLI/route registration, public API, conditional compilation, test discovery). When no tooling is available, say so as a coverage gap.

4. For each candidate, read the full candidate files, at least one nearby caller, and nearby tests to see whether the behavior contract is already captured, before classifying.

Skip or de-prioritize generated files, vendored dependencies, lockfiles, snapshots, fixtures, minified bundles, protobuf/OpenAPI generated clients, and build artifacts unless the user scopes them. When duplication appears in generated output, recommend changing the generator, schema, or template, or exclude it from slimming findings. Do not recommend hand-editing generated output.

Read surrounding code before judging. Similar shape is not enough. The question is whether one shared behavior path would be clearer, safer, and easier to validate.

Step 5: Classify opportunities

Use these labels:

• Do now - small, obvious, low risk, and already covered by meaningful validation
• Do with tests - likely worthwhile, but needs focused tests before implementation
• Defer - valid but too broad, risky, or low-value for current churn
• Leave alone - duplication is clearer, faster, intentional, or likely to diverge

These labels are audit recommendations only. Even Do now does not authorize this skill to edit code; it means the proposed change appears safe for a separate implementation pass.

Every classified item must cite:

• representative file paths and line ranges
• the repeated behavior or wrapper behavior observed
• the behavior invariant that must remain identical
• existing validation evidence or the missing validation gap
• why similar-looking cases are included, excluded, or left alone

Most findings are not merge blockers. Say so clearly.

For Do now, cite behavior-specific validation evidence: exact test files or cases that exercise the preserved behavior, or explain why the change is purely local, mechanical, and directly inspectable. If you cannot cite behavior-specific evidence, classify as Do with tests or Defer.

For dead-code and commented-out-code deletions, the evidence is the no-reference proof: the search that found zero live references and the indirection paths ruled out (reflection, dynamic dispatch, DI, serialization, plugin/CLI/route registration, public API, conditional compilation, test discovery). A symbol unreferenced and unreachable through any of those paths is a valid Do now. If it is exported or reachable through an unproven path, classify as Do with tests or Defer and say which path you could not rule out.

Step 6: Evaluate tradeoffs

For every recommendation, answer:

• What behavior must remain identical?
• What gets smaller: LOC, concept count, duplicated call sites, public API surface, dependency count, file count, or test surface?
• What might get worse: runtime performance, bundle size, allocation count, readability, coupling, test brittleness, or onboarding clarity?
• Why is the proposed centralization better than the current duplication?
• What validation would prove the change is safe?
• Are duplicated checks intentionally defensive at separate boundaries, and what fails closed if one layer is bypassed?

If a slimmer implementation affects hot paths, rendering loops, query batching, serialization, startup, memory layout, build output, or binary size, require performance-sensitive validation before classifying it as Do now.

Step 7: Report

It is acceptable and often correct to return zero high-value opportunities. Do not manufacture a slimming recommendation to fill the report. Prefer a well-justified Leave alone finding over a low-confidence abstraction.

The markdown template below is the body of the written deliverable. It is a read-only set of proposals: it groups findings by action label and intentionally opts out of the checkbox Fix protocol in the Output Contract (there is nothing for an implementer to flip here). Wrap it with the boxed inline header and boxed conclusion table when emitting to the transcript; the conclusion table remaps the shared columns exactly as defined in the Output Contract section below (Type = rec/found, Priority carries Risk, Action = proposed/recommend).

Use this format:

## Code Slimming Audit: [scope]

Context:
- Languages/frameworks: [detected]
- Baseline validation run: [commands and results; implementation validation not run because this audit is read-only]
- Validation gaps: [missing, noisy, skipped, or unavailable checks]

### High-Value Opportunities

**Do with tests** `services/*/list-items.*` - Centralize repeated pagination and filter parsing.
Affected files: `services/users/list-items.*`, `services/projects/list-items.*`
Evidence: `services/users/list-items.ts:24-58`, `services/projects/list-items.ts:19-55`
Current duplication: both modules parse the same page, limit, sort, and filter parameters.
Refactor shape: extract a shared parser with endpoint-specific allowlists.
Behavior invariant: page and limit defaults, max-limit handling, sort allowlists, and error messages stay identical.
Call-site impact: 2 endpoint handlers, no public import path changes.
Why better: one behavior path for defaults and validation, with fewer divergent call sites.
Tradeoffs: one shared helper couples list endpoints to a common pagination contract.
Risk: medium
Validation needed: add boundary tests for page and limit values, then run lint/type/build/test commands.

**Do now** `src/legacy/format.ts` - Delete unused module.
Evidence: `src/legacy/format.ts:1-120` defines `formatLegacy`; no imports of `legacy/format` or
references to `formatLegacy` in `src/`, `test/`, config, or route tables (`rg -n "legacy/format|formatLegacy"`).
No-reference proof: not exported from the package index, not referenced by string key, not a DI/CLI/route registration.
Behavior invariant: none; nothing reaches this code.
Why better: removes a whole dead module and its transitive imports.
Tradeoffs: none if the no-reference proof holds.
Risk: low
Validation needed: type and build pass after deletion; grep confirms zero references.

### Removed-Code Safety Review

Include this section only when reviewing a diff or PR that removed code.

**Needs evidence** `[area]`
Removed behavior: [code path, wrapper, branch, fallback, type, validation, or dependency removed]
Replacement path: [what now handles it]
Behavior invariant: [what must still happen]
Evidence checked: [diff lines, call sites, tests, type checks]
Risk: [low/medium/high]
Validation needed: [specific command/test/case]

### Low-Value Or Risky Opportunities

**Leave alone** `integrations/*` - Duplication is likely to diverge per provider.
Why not: each provider already has different retry, auth, pagination, and error semantics.

### Summary

- High-value opportunities: 1
- Low-value or risky opportunities: 1
- Merge blockers: none from this audit lens
- Residual risk / skipped areas: [large dirs, generated files, expensive checks, external services]
- Net recommendation: [slim / defer / leave mostly unchanged], based on risk-adjusted maintenance value, not LOC delta

If no useful slimming opportunities are found, say so explicitly:

### High-Value Opportunities
None found within scope.

### Search Coverage
- Scope inspected: [diff/path/repo areas]
- Patterns checked: [dead code/unused symbols, orphan files, clones, wrappers, duplicate schemas, repeated parsers, adapters, utils, comment walls]
- Files/directories skipped: [generated/vendor/tests/etc.]
- Validation checked: [commands/tests found or unavailable]

### Why no action is recommended
- Existing duplication appears intentional because: [...]
- Thin wrappers are retained because: [...]
- Shared abstraction would likely worsen: [...]

### Low-Value Or Risky Opportunities
[optional leave-alone observations]

### Summary
- High-value opportunities: 0
- Low-value or risky opportunities: N
- Merge blockers: none from this audit lens
- Residual risk: [what was not inspected]
- Net recommendation: leave mostly unchanged

Keep the report concise. Show the refactor shape, not a lecture.

Common Patterns

Pattern-by-pattern recognition aids - dead code and unused symbols, exact and intra-file clones, commented-out code and comment walls, repeated boundary parsing, near-twin adapters, duplicate data shapes, wrapper layers, oversized helper modules, and performance-sensitive slimming - live in references/patterns.md. Consult it when a candidate's category or safe-collapse shape is unclear.

Output Contract

See references/output-contract.md for the full contract.

• Skill name: CODE-SLIMMING
• Deliverable bucket: audits
• Mode: always-on for audit and review invocations. Every invocation that analyses existing code emits the full contract - boxed inline header, body summary inline plus per-finding detail in the deliverable file, boxed conclusion, conclusion table. For a quick factual question (e.g., "what is wrapper removal?") respond freely without the contract.
• Deliverable path: docs/local/audits/code-slimming/<YYYY-MM-DD>-<slug>.md
• Severity scale: this skill overrides the shared P0-P3 scale, which the contract permits via its scale-migration note. Findings are classified by action - Do now | Do with tests | Defer | Leave alone - plus a Risk: low | medium | high field per finding (see the Workflow). This skill proposes deletions, not severity-ranked defects. Old -> new: P0-P3 priority is not used; Risk replaces the Priority column (see Conclusion-table columns below).
• Conclusion-table columns (the shared table in references/output-contract.md is code-review-flavored; map it for this skill): Type is rec for opportunities or found when reviewing removed code; the Priority column carries this skill's Risk value (low | medium | high), not a P-level; Action is proposed for opportunities and recommend for removed-code safety findings. The file-deliverable groups findings by action label (Do now, Do with tests, Defer, Leave alone), not by ## P0-style headings.

Related Skills

• anti-slop - code quality audit for AI-like patterns, over-abstraction, noisy comments, hallucinated APIs, and test theater.
• anti-ai-prose - prose-slimming for AI voice in docs, comments, and docstrings. Use when the goal is removing AI-written prose patterns rather than reducing code size.
• code-review - correctness audit for bugs, regressions, races, edge cases, and broken contracts.
• testing - writes and debugs tests required before implementing a slimming recommendation.
• security-audit - reviews security-sensitive code where "defensive" duplication may be necessary.
• full-review - quick four-pass merge-safety audit; does not include code-slimming by default.
• deep-audit - comprehensive repo audit; includes code-slimming as a Wave 2 maintainability pass.

Rules

1. Do not edit code. This skill reports opportunities only.
2. Do not write tests. Name missing tests and route test implementation to testing.
3. Do not chase LOC alone. Smaller code that is slower, more coupled, or harder to understand is not automatically better.
4. Require a concrete refactor shape. Every recommendation must describe what would be extracted, deleted, moved, or centralized.
5. Explain why. Every recommendation must state the maintenance benefit and the behavior that must remain unchanged.
6. Validate before calling it safe. A Do now recommendation needs behavior-specific validation evidence, or a purely local mechanical invariant that was directly inspected.
7. Respect language idioms. Generic helpers, inheritance, macros, templates, reflection, and dynamic dispatch have different costs across Python, JavaScript/TypeScript, Java, Rust, C/C++, shell, and infrastructure code.
8. Keep bugs and vulnerabilities in their lanes. Route correctness findings to code-review and security findings to security-audit.
9. Prove dead before deleting. Never recommend deleting a symbol, file, or dependency as unused without a no-reference search and an explicit list of indirection paths ruled out (reflection, dynamic dispatch, DI, serialization, plugin/CLI/route registration, public API, conditional compilation, test discovery).
10. Trim comments by deletion, not rewriting. Flag only commented-out code, comments that restate the code, and dead banner walls. Keep intent, invariants, links, license, and pragmas. Route AI-voice prose rewrites to anti-ai-prose.