find-dead-code

name	find-dead-code
description	Find dead code using parallel sub-agent analysis and optional CLI tools, treating code only referenced from tests as dead. Use when the user asks to "find dead code", "find unused code", "find unused exports", "find unreferenced functions", "clean up dead code", or "what code is unused". Analysis-only — does not modify or delete code.

Find Dead Code

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

In an incomplete or abandoned implementation, a declared-but-unused symbol may be intended-but-not-yet-used. When git history shows it was added as a deliberate part of an unfinished stack, recommend investigate rather than delete.

Step 1: Detect Languages, Scope & Test Boundaries

Determine the project structure:

1. Check for config files: package.json, tsconfig.json, pyproject.toml, setup.py, Package.swift, .xcodeproj, Cargo.toml, go.mod, pom.xml, build.gradle
2. Glob for source files: **/*.ts, **/*.py, **/*.swift, **/*.go, **/*.rs, **/*.java
3. Identify source roots — where production code lives (e.g., src/, lib/, Sources/)
4. 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 sub-agent'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 Sub-agents (Core)

Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so sub-agents running them concurrently wipe each other's state and return failures that look like real defects. Name any such tier to every sub-agent as off-limits.

This is the primary analysis. Launch one sub-agent per top-level source directory from Step 1 with spawn_agent / wait_agent using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. State the count explicitly when emitting the calls. Each sub-agent's prompt directs it to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated git worktree created under $TMPDIR and discarded afterward. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. Afterward the sub-agent verifies that git worktree list no longer shows the worktree, that git status --short is clean, that HEAD is still on the branch it started on, and that the shared tree's dependency directory still resolves (a destroyed install leaves git status clean, since it is gitignored). Damage the sub-agent cannot repair is reported with the exact repair command in place of findings.

Sub-agent Strategy

Each sub-agent receives:

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

Sub-agent Task

Each sub-agent 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 sub-agents 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:

1. 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
2. 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.
3. 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"
4. Cross-package references: In monorepos, verify a symbol isn't imported by a sibling package before declaring it dead
5. Design docs / specs / roadmaps: If the project has spec files, roadmaps, or TODO files (e.g., .turbo/specs/, 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:

1. 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.
2. 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).
3. Vestigial enum cases: Enum cases defined but never constructed or matched against in production code.
4. 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 no dead code is found, report that explicitly and note any scope limitations or analysis caveats.