necessary-code-audit

Necessity code audit

Principles

The optimization goal is "whether it is currently necessary," not just "whether it has zero references." Even if a symbol still has callers, it may merely be a wrapper layer, compatibility surface, defensive branch, stale public API, or hypothetical extension point.

The core question is: this code is used, but does the current code really still need it?

Do not delete real runtime constraints. Branches representing loading, empty data, errors, permissions, lifecycle, browser, SSR, quotas, external input, or domain nullable states must be retained.

Do not treat ordinary comments as cleanup targets. Only delete or rewrite comments when they are already outdated, incorrect, misleading, or orphaned because of code deletion.

Do not stop after finding the first obvious cleanup point. For the directory or feature specified by the user, you must audit the entire scope first before reporting "no more" or asking the user to continue.

Skill collaboration

This skill is the main entry point for three cleanup skills:

Use necessary-code-audit to determine "whether code that is already used is still necessary."
Use unused-code-audit to prove whether a deletion candidate still has consumers.
When the goal involves page state, query/mutation flows, permissions, errors, or user-visible behavior, use page-flow-cleanup-audit。

Do not depend on repository-specific graph tools. Prefer file lists, language tools, build/type checks, manifests, import graphs, and text search available in the current environment.

Boundaries

This skill only answers "even if someone is using it, is this abstraction/behavior/API still necessary?"

Suitable for this skill:

Wrappers, facades, compatibility aliases, default values, fallbacks, optional fields, or configuration that have callers.
Helpers that are called from multiple places but whose callers could directly use more basic primitives.
Public APIs that are still imported but are merely historical compatibility surfaces or stale entry points.
Whether defensive branches, try/catch, optional chaining,as any , or old-format compatibility represent real constraints.
Whether two sources of truth, duplicate caches/stores/queries/derived computations need to be merged.

Not suitable to be completed by this skill alone:

You only want to prove whether a file, export, or type has zero consumers; use instead unused-code-audit。
Delete dead code with no callers; first use unused-code-audit to complete consumer proof.
Cleanup of page state, permissions, query/mutation chains, or user-visible flows; use instead page-flow-cleanup-audit。

Collaboration rules:

If a candidate appears to have zero consumers, pause the necessity judgment and switch to unused-code-audit 's deletion proof.
If a candidate still has consumers, continue judging whether it is necessary, whether callers can be replaced, and whether the public surface should be shrunk.
unused-code-audit 's conclusion can only indicate "whether unused items can be safely deleted"; it cannot replace this skill's judgment of "used but unnecessary."

Baseline

At the start, you must collect:

git status --short --untracked-files=all
git diff --name-status -- <scope>
git diff --cached --name-status -- <scope>
Target scope file list, preferably using rg --files <scope>。
Current imports, exports, public entry points, and direct consumers.
Scoped symbol inventory: exported functions/types/constants, non-exported helpers, config fields, and duplicate literals.
Impact map: same-package consumers, package entry points, direct app/package imports, and downstream packages in the manifest.

Do not assume staged or dirty changes were caused by you. Do not roll back unrelated changes.

Depth threshold

These checks must be completed both before editing and before finishing:

Inventory every file and meaningful export/helper within scope, not just the file the user mentioned first.
Split candidates into "zero-consumer candidates" and "has-consumers-but-may-be-unnecessary candidates"; hand zero-consumer candidates to unused-code-audit for proof.
For candidates with consumers, inspect at least one representative call site in each consumption area before deciding whether the abstraction is necessary.
For replaceable candidates, confirm whether callers can use the existing primitive directly, and which exports/helpers/types would be orphaned after replacement.
For public API changes, confirm package exports and downstream package/app typecheck that covers the change surface.
After each cleanup batch, re-search for leftover names, old import paths, duplicate literals, and newly orphaned helpers.
Stop only when all remaining candidates have been classified as real constraints, intentionally retained public API, or beyond the risk scope of the current request.

If these checks surface more work, keep handling it in the same round. Do not require the user to say "continue deep check" in order to proceed.

Candidate classification

Classify every meaningful file, export, method, field, option, fallback, and branch in the target scope:

当前必要: Required by current product behavior or platform/runtime constraints.
可直接替代: A wrapper/facade whose underlying primitive callers can use directly.
兼容面: Legacy exports, optional fields, defaults, aliases, factories, configuration, or public types retained for external or historical consumers.
防御分支: try/catch, fallback, optional chaining, null guards, feature detection, or dirty-data handling.
假设性能力: An API surface with no current callers, or only hypothetical future value.
重复来源: A second cache, store, query, invalidation path, state source, or derived computation.
疑似死代码: Appears to have no real consumers; do not delete it directly within this skill, hand it off to unused-code-audit for proof.
真实约束: SSR, browser storage availability, quotas, permissions, loading/error/empty lifecycle, external input, or legitimate domain nullable state.
仅文档: Comments or documentation. Keep them unless they are outdated, misleading, or orphaned by code changes.

Necessity questions

Before editing, answer for each candidate:

Does the current code actually need this behavior?
If it has callers, do the callers need this abstraction, or can they call the existing primitive directly?
Is it protecting real runtime/domain state, or historical compatibility/assumptions?
If backward compatibility is not needed, can the public type, export, or configuration be deleted?
Does deletion change current product behavior? If so, does that match the request intent?
After deletion, which methods, imports, exports, comments, tests, or documentation become meaningless?

When what the user wants to delete is actually a real constraint rather than defensive code, point that out explicitly.

Cleanup order

First delete wrappers, facades, and compatibility layers.
Replace call sites with direct primitives.
Delete newly orphaned methods, helpers, imports, exports, and public types.
Delete unused config keys, default values, optional fields, feature flags, and old comments orphaned by code deletion.
Delete defensive branches that only hide impossible or stale states.
Re-run residual searches after each deletion of a source or public API.

Do not create new abstractions in order to delete old abstractions.

Comment cleanup is only an incidental action of code cleanup. Do not include "low-value comments" in the cleanup order unless they are wrong or orphaned.

Evidence

Structural evidence:

File inventory of the target directory or feature.
Import/export searches for wrappers, methods, and exported symbols.
Manifests, re-export files, framework conventions, generated files, and type declarations.
Use language tooling when available: compile diagnostics, test coverage, dependency analysis, or IDE references.
For each changed public helper, check at least one representative call site in each consuming package/app.
Choose downstream package/app typecheck based on the real import graph, rather than only checking the defining package.

Text residual searches:

Deleted file stems and import paths.
Deleted symbol names and member names.
Compatibility-related words:legacy、deprecated、backward、compat、fallback、debug, old-format comments, commented-out code.
Defensive patterns:try、catch, optional fields, optional chaining,as any, constant boolean parameters, default config values.
Duplicate literals and equivalent local helpers, which may indicate that a shared primitive is not being reused.

Automated unused-export or dependency analysis tools can only serve as candidate generators. After finding a zero-consumer candidate, enter the proof process of unused-code-audit ; this skill continues to handle candidates that are "still used but no longer necessary."

Verification

Run the narrowest check that covers the change boundary:

After public API changes, first run typecheck/build for the defining module or library.
Typecheck or narrow eslint for directly consuming packages.
When imports, public exports, or shared validation/formatting behavior change, run downstream app/package typecheck.
Perform residual rg。
git diff --check -- <scope>on deleted symbols and old import paths; if there are staged changes, also run git diff --cached --check -- <scope>。

If a broad typecheck fails, explain whether the failure is related to this cleanup.

Report

Report:

Deleted: wrappers, compatibility surfaces, defensive branches, stale public APIs, and direct replacements.
Kept: real runtime/domain constraints, and why it is not meaningless defensive code.
Verified: commands, results, residual searches, unrelated dirty files, or unrelated failures.

Clearly state which candidates were handed off to unused-code-audit for proof, and which candidates are "still used but no longer necessary" and handled by this skill.