unused-code-audit

Unused Code Audit

Principles

Treat every automated result as a candidate, not as proof. Delete only after usage, entry points, side effects, and public API risks have all been ruled out.

Prefer small, evidence-backed deletions. Do not shrink the public API merely because a type or export name has no direct import; generated declarations and inferred consumer types may still depend on it.

This skill answers "does anyone still consume it?". It does not answer the broader "is it still necessary?". For code that is "used but unnecessary", switch to necessary-code-audit。

Do not stop after finding the first unused symbol. For a user-specified directory or feature, you must audit all files, exports, local helpers, and re-export paths within scope before reporting completion.

Do not delete or rewrite comments as unused code unless the related code is deleted, or the comment is already outdated/misleading.

This skill is one of three cleanup skills:

Use unused-code-audit to prove whether code still has consumers.
When code is used but may be unnecessary, use necessary-code-audit。
When the goal involves page state, queries, mutations, permissions, errors, or user-visible behavior, use page-flow-cleanup-audit。

Boundaries

This skill only answers "whether real consumers exist, and whether it can be safely deleted when there are zero consumers".

Suitable for this skill:

Whether a file, export, type, constant, component, hook, or helper is imported or referenced by no one.
Whether re-exports, barrel exports, type-only imports, dynamic string keys, framework entry points, and side effects constitute real consumption.
After deleting zero-consumer code, clean up direct exports, orphaned imports/types, and leftover paths.

Not suitable to be completed by this skill alone:

A helper has callers but is only a thin wrapper; switch to necessary-code-audit。
The public API is still imported, but may only be a historical compatibility surface; switch to necessary-code-audit to determine whether to migrate callers and shrink the public surface.
Whether defensive branches, fallbacks, default values, and optional fields have domain meaning; switch to necessary-code-audit。
Whether page state, permissions, query/mutation, and source-of-truth should be cleaned up; switch to page-flow-cleanup-audit。

Collaboration rules:

When a search finds that a candidate still has real consumers, stop the "unused" conclusion; if it still looks unnecessary, hand off to necessary-code-audit。
Do not judge already-used code as unused just because "the callers can be rewritten". That is a necessity question, not an unused question.
This skill can delete zero-consumer code, but is not responsible for migrating callers that have consumers, unless the migration is merely deleting newly orphaned direct references within the same file.

Baseline

First check the workspace state:git status --short --untracked-files=all。
Check unstaged and staged changes in the target scope:git diff --name-status -- <scope>、git diff --cached --name-status -- <scope>。
Build the target scope file list, preferably using rg --files <scope>。
Before trusting automated unused results, check imports, exports, manifests, framework entry points, generated files, and direct consumers.
Before deletion, build an impact map: define package exports, same-package consumers, downstream package/app imports, and scripts/tests that may import the public surface.

Depth threshold

Before completing an unused-code audit, you must:

List every file and exported symbol within the request scope.
When a local helper can only be reached through an export aggregate or public function, include it in the check as well.
Search for exact symbols, import paths, file stems, barrel exports, type-only imports, property access, string keys, and test/script usage.
Explicitly divide the results into "no consumers, may proceed per the deletion criteria" and "has consumers, exit the unused determination and switch to necessary-code-audit".
Continue checking public entry points, framework conventions, side effects, and dynamic references only for no-consumer candidates.
After editing, search again for the deleted names and old paths to catch orphaned exports and stale imports.
When the public surface changes, run the defined package validation and validation for affected downstream package/apps.

Do not require the user to prompt again before continuing from one candidate to the next within the same request scope.

Candidate classification

Classification before deletion:

文件: module, route, style, setup, generated entry, or side-effect file.
运行时导出: function, component, hook, class, constant, store, or factory.
公共类型/API: exported interface/type/config used by a declaration file or factory return type.
成员: property, method, action, enum member, or configuration field.
本地 helper: non-exported helper within a single file.

The classification determines the risk level. Public APIs, framework entry points, side-effect files, and persisted data require stronger evidence.

Evidence

Collect evidence in the following order:

Structure:
- File inventory for the directory or feature scope.
- Public entry points, re-export files, framework conventions, generated files, and type declarations.
- Use language tooling, compiler diagnostics, dependency analysis, or IDE references when available.
- Package export map and workspace manifest, used to determine downstream typecheck targets.
Text search:
- Use rg to search for exact symbol names, file stems, import paths, aliases, and case variants.
- Search the definition locations and all possible consumer root directories, not only the file or folder to be deleted.
- For members, search for direct access, destructuring, index access, callbacks, configuration objects, and type-only references.
- When a shared symbol appears unused, search for duplicated local constants or helper logic; this only indicates that necessary-code-audit may need to be promoted for reuse, and does not prove that the current symbol is still consumed.
Candidate scan:
- If there is a local unused-export script or dependency analyzer, it can be used to generate candidates.
- When the tool supports scoped roots, pass in the target root directory.
- Automated output is only a clue, not proof.

False positives

Keep the code unless the following cases are ruled out:

re-export, alias, wrapper export, or same-file aggregate usage.
Framework conventions: entrypoint, layout, metadata, middleware, loading/error files, and generated files.
Public module exports, public entry files, generated declarations, or externally inferred types.
Dynamic usage through strings, registry, map, config arrays, content metadata, or dependency injection.
Side effects: styles, polyfills, providers, setup modules, storage keys, analytics, subscriptions, and initialization.
An exported aggregate internally consumes exported sub-parts.

Deletion Criteria

Delete only if all are satisfied:

Structural checks and text search both show no real consumers, except for allowed re-export references.
The candidate is not a framework entry, side-effect module, generated artifact, or public API requirement.
The request scope allows deletion.
The edit is surgical: delete only the candidate, direct export, and newly orphaned import/type.

Verification

For each deleted symbol, file stem, and import path, do a residual rg。
Run the narrowest relevant typecheck.
When the public API changes, verify the defining module first, then build or typecheck the affected consumers.
When a public helper/constant is replaced by another package/app, also typecheck those consumers.
Run git diff --check -- <scope>; if there are staged changes, also run git diff --cached --check -- <scope>。
If verification fails, state whether the failure was caused by this deletion or is unrelated workspace state.

Report

Report three categories:

Deleted: what was deleted, and the evidence.
Handed off: which candidates still have consumers and therefore are not unused, and should be judged for necessity by necessary-code-audit .
Retained: important false-positive candidates, and the reason for retaining them.
Verified: commands run, results, unrelated dirty files, or failures.