Find Dead Code

Identify dead code in a codebase. Core rule: code only used in tests is still dead code. Only production usage counts.

Step 1: Detect Languages, Scope & Test Boundaries

Determine the project structure:

Check for config files:

package.json

tsconfig.json

pyproject.toml

setup.py

Package.swift

.xcodeproj

Cargo.toml

go.mod

pom.xml

build.gradle

Glob for source files:

**/*.ts

**/*.py

**/*.swift

**/*.go

**/*.rs

**/*.java

Identify source roots — where production code lives (e.g.,
```
src/
```
,
```
lib/
```
,
```
Sources/
```
)
Partition the codebase into analysis units by top-level source directories (e.g.,
```
src/auth/
```
,
```
src/api/
```
,
```
src/utils/
```
,
```
lib/models/
```
). Each directory becomes one subagent's scope in Step 3.

If the user specified a scope, restrict analysis to that scope.

Test File Patterns

Establish which files are test files. Code referenced ONLY from these locations is dead.

Language	Test file patterns
TS/JS	`.test.{ts,tsx,js,jsx}` , `.spec.{ts,tsx,js,jsx}` , `__tests__/` , `__mocks__/` , `*.stories.{ts,tsx,js,jsx}`
Python	`test_.py` , `_test.py` , `tests/` , `test/` , `conftest.py`
Swift	`Tests.swift` , `Test.swift` , `Tests/*` , `UITests.swift` , `XCTestCase` subclasses
Go	`_test.go` , `testdata/*`
Rust	`tests/` , `benches/` , `#[cfg(test)]` modules (inline test modules within source files)
Java/Kotlin	`src/test/*` , `Test.java` , `Tests.java` , `Spec.java` , `*Test.kt`
General	`fixtures/` , `__fixtures__/` , `mocks/` , `testutils/` , `testhelpers/` , `spec/`

Also exclude: test runner configs (

jest.config.*

vitest.config.*

pytest.ini

), storybook files, benchmark files.

Step 2: Quick Wins — CLI Tools (Optional)

If a CLI tool is installed, run it as a fast first pass for zero-reference dead code.

Language	Tool	Check	Run
TS/JS	`knip`	`npx knip --version`	`npx knip --no-exit-code`
Python	`vulture`	`vulture --version`	`vulture <src_dirs> --min-confidence 80`
Swift	`periphery`	`which periphery`	`periphery scan --skip-build`
Go	`deadcode`	`which deadcode`	`deadcode ./...`
Rust	compiler warnings	—	`cargo build 2>&1 \| grep "dead_code"`

Important limitation: CLI tools count test imports as real usage. They cannot detect code that is only used in tests. They only find symbols with literally zero references anywhere. Step 3 is required for test-only detection.

If no CLI tool is installed, skip to Step 3. Do not ask the user to install anything.

Step 3: Test-Only Analysis — Parallel Subagents (Core)

This is the primary analysis. Spawn parallel background subagents to systematically find code that is only referenced from tests.

Subagent Strategy

For each top-level source directory identified in Step 1, launch one background subagent (using the Agent tool with

run_in_background: true

). Each subagent receives:

Its assigned directory to scan for exported symbols
The test file patterns from Step 1
The full project root path so it can grep across the entire codebase

Subagent Task

Each subagent performs these steps on its assigned directory:

a) Find exported/public symbols:

Language	Exported symbol patterns
TS/JS	`export function` , `export const` , `export let` , `export var` , `export class` , `export interface` , `export type` , `export enum` , `export default` , `module.exports`
Python	Top-level `def` and `class` in non- `_` -prefixed modules, module-level constants ( `FOO = ...` ), symbols in `__all__` , public functions (no `_` prefix)
Swift	`public func` , `public var` , `public let` , `public class` , `public struct` , `public enum` , `public protocol` , `open class` , `open func` , `open var`
Go	Capitalized identifiers: `func FooBar` , `type FooBar struct` , `var FooBar` , `const FooBar` (Go uses capitalization for public visibility)
Rust	`pub fn` , `pub struct` , `pub enum` , `pub trait` , `pub const` , `pub static` , `pub type` , `pub mod`
Java/Kotlin	`public class` , `public static` , `public void` , `public` fields, `val` / `var` properties, `fun` (top-level), `@Bean` , `@Component` , `@Service` annotated classes

b) For each symbol, grep across the entire codebase for references, excluding:

The definition file itself

Generated/vendored directories (

node_modules/

dist/

build/

vendor/

__pycache__/

.tox/

.build/

DerivedData/

target/

)

c) Classify each reference as test or production based on the test file patterns.

CRITICAL — same-module references count as production usage. A symbol called by another production file within the same module/package is alive. Do not report symbols as "dead" when they have zero external callers but are used internally. Only report symbols with zero production references from any file. "Unnecessarily public" (could be

internal

/unexported) is a visibility issue, not dead code — do not include it.

d) Report structured results for each symbol:

Symbol name, type (function/class/const/etc.), definition file and line range
Number of production references (with file paths) — including same-module references
Number of test references (with file paths)
Classification:
```
dead
```
(zero prod refs anywhere),
```
test-only
```
(only test refs),
```
alive
```
(has prod refs)

Merging Results

After all subagents complete, collect and merge their results. Deduplicate any symbols that appear in multiple reports (e.g., re-exports).

Step 4: Filter, Classify & Evaluate

Apply these filters to the merged results from Steps 2 and 3:

Framework entry points: Skip symbols used by convention — React components in barrel files, Django views in URL configs, Go
```
init()
```
and
```
main()
```
functions, Go interface implementations, Rust
```
main()
```
, Rust trait implementations,
```
#[derive(...)]
```
generated code, CLI handlers registered in main, magic/lifecycle methods (
```
__init__
```
,
```
__repr__
```
), serialization methods (
```
to_json
```
,
```
from_dict
```
), interface/protocol implementations
Re-export chains: Trace barrel files (
```
index.ts
```
,
```
__init__.py
```
) before declaring a symbol dead. A symbol re-exported through a barrel may have indirect consumers.
Dynamic usage: Flag symbols that might be used via reflection (
```
getattr
```
,
```
importlib
```
,
```
reflect
```
package in Go,
```
proc_macro
```
in Rust), string-based lookups, or decorator/attribute registration as "likely dead" rather than "definite"
Cross-package references: In monorepos, verify a symbol isn't imported by a sibling package before declaring it dead
Design docs / specs / roadmaps: If the project has spec files, roadmaps, or TODO files (e.g.,
```
.turbo/spec.md
```
,
```
ROADMAP.md
```
,
```
TODO.md
```
), cross-reference test-only findings against them. Test-only APIs may be planned features awaiting integration — flag as investigate rather than delete

Classify each finding:

Definite dead: zero references outside its definition file
Test-only dead: references exist, but ALL are in test files
Likely dead: uncertain due to dynamic usage, framework conventions, or complex re-export chains

Evaluate Findings

Run the

/evaluate-findings

skill on the classified results to verify each finding against the actual code and weed out false positives. Read the full definition file for each finding — not just the flagged symbol. The surrounding code may reveal that the feature is already implemented differently (e.g., a public

ping()

method may be test-only while a private keepalive loop in

handleConnect()

does the real work).

Proceed with the evaluation results in the next section.

Recommend Action

For each surviving finding, assign a recommendation:

Signal	Recommendation
No tests, no production usage	delete
Has tests but no production usage, and no spec/roadmap reference	delete (method + test assertions)
Has tests but no production usage, referenced in spec/roadmap/TODO	investigate (planned feature, not dead)
Partially wired up, unclear intent, or needs domain context	investigate

For findings marked investigate, run the

/investigate

skill to determine whether the code is a planned feature, an unwired integration, or truly dead.

Common Dead Code Patterns

Watch for these high-yield patterns that tools and simple grep often miss:

Test-only state accessors: Public properties/methods that expose internal state solely for test assertions (e.g.,
```
isEnabled
```
,
```
count
```
,
```
currentItems
```
). The module's production consumers use behavior (events, callbacks, side effects) — only tests peek at the internal state. When removing these, the corresponding test assertions must also be removed or rewritten to use behavior-based verification.
Unused data model fields: Properties on serializable types (Codable structs, dataclasses, POJOs) that are decoded but never read by any production code. When removing a field from a serializable type, also update all data files that encode it (JSON, YAML, XML, database schemas, migration files).
Vestigial enum cases: Enum cases defined but never constructed or matched against in production code.
Orphaned convenience methods: Public wrappers that call through to another public method with slightly different parameters, where all callers use the underlying method directly.

Adjacent Findings

While scanning for dead code, note (but do not act on) these related issues for the user:

Bugs near dead code: Dead code often neighbors buggy code — a missing call, a wiring gap, or an incomplete integration
Unwired features: Code that is "almost alive" — defined, tested, but not connected to the rest of the system. Distinguish from truly dead code.

Step 5: Present Findings

Group results by confidence level:

Definite Dead (zero references outside definition)

File	Symbol	Type	Line Range	Recommendation

Test-Only Dead (referenced only in tests)

File	Symbol	Type	Test files referencing it	Recommendation

Likely Dead (verify manually)

File	Symbol	Type	Reason for uncertainty	Recommendation

Include:

Total count per category
Estimated removable lines
Suggested removal order (leaf dependencies first)

Rules

If more than 8 top-level source directories are identified, ask the user to narrow scope or group related directories into fewer subagent batches.
If no dead code is found, report that explicitly and note any scope limitations or analysis caveats.

find-dead-code

NPX Install

Tags

SKILL.md Content