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:

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 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.

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.

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. Use the Agent tool to launch one subagent per top-level source directory from Step 1 in a single assistant message so they run concurrently. Each Agent call uses model: "opus" and does not set run_in_background. Expect one Agent tool call per directory, capped at 8 by the Rules section. State the count explicitly when emitting the calls.

Subagent Strategy

Each subagent 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

Subagent Task

Each subagent performs these steps on its assigned directory:

a) Find exported/public symbols:

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:

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