dead-code-cleanup

name	dead-code-cleanup
description	Identify and safely remove dead code, deprecated code, and unused exports from codebase. Use when you need to clean up unused or obsolete code.
allowed-tools	Glob, Grep, Read, Edit, Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(go:*), Bash(git status:*), Bash(tsc:*), Task
disable-model-invocation	true

Dead Code Cleanup Command

Purpose

Systematically identify and remove unused code while maintaining project integrity.

Target Code:

• Unused exports/functions/classes with no references
• Deprecated code without active migration plan
• Orphaned files (no imports from anywhere)
• Unreachable code paths

Critical Constraint: Project must build and pass all tests after cleanup.

---

User Input

$ARGUMENTS

Interpretation:

Input	Action
Empty	Analyze entire codebase
Path (e.g., src/legacy/)	Analyze specified directory
--dry-run	Report only, no deletions
--auto	Delete HIGH confidence items without confirmation

---

Preservation Rules (NEVER DELETE)

Absolute Preservation

Category	Detection Method	Examples
Public API	package.json exports, index.ts re-exports	Library entry points
Planned Features	TODO/FIXME with ticket/issue	// TODO(#123): implement
Framework Conventions	Path-based (pages/, app/, api/)	Next.js routes, NestJS modules
Test Infrastructure	Imported by *.test.*, *.spec.*	Fixtures, mocks, test utils
Dynamic Imports	import(), require() patterns	Lazy loading, code splitting
Build Dependencies	Referenced in package.json scripts	Build tools, CLI scripts
External Contracts	GraphQL types, API schemas	Schema definitions

Special Cases

Exported but unused internally:

• Public library → PRESERVE (external consumers unknown)
• Private app → Flag for review

Deprecated with timeline:

• Deadline NOT passed → PRESERVE
• Deadline passed + no usage → DELETE

---

Analysis Workflow

Phase 1: Context Gathering

1.1 Detect Project Type

# Framework detection
[ -f "next.config.js" ] && echo "Next.js"
[ -f "tsconfig.json" ] && echo "TypeScript"
[ -f "go.mod" ] && echo "Go"

1.2 Identify Package Scope

# Public library vs private app
grep '"private": false' package.json && echo "PUBLIC_LIBRARY"

1.3 Map Public API Surface

• Check package.json exports field
• Find index.ts re-exports
• List Go exported symbols (capital letter)

Phase 2: Dead Code Detection

2.1 Unused Exports

For each export statement:

1. Search for import references across codebase
2. Check dynamic import patterns
3. Verify not in public API surface

2.2 Deprecated Code

grep -rn "@deprecated" --include="*.ts" --include="*.go"
grep -rn "DEPRECATED" --include="*.ts" --include="*.go"

2.3 Orphaned Files

Files not imported anywhere:

• Exclude: entry points, config files, scripts
• Exclude: test files, type declarations
• Flag: utility files with no imports

Phase 3: Validation

For each candidate:

1. Cross-reference check: Search all possible import patterns
2. String reference check: Filename as string (dynamic loading)
3. Comment reference check: TODO/FIXME mentioning future use
4. Preservation rule check: Apply rules from above

Confidence Classification:

Level	Criteria	Action
HIGH	No references, not preserved, clear dead code	Auto-delete (with --auto)
MEDIUM	No direct refs, but string/comment mentions	Ask confirmation
LOW	Exported publicly, ambiguous usage	Report only

Phase 4: Safe Deletion

4.1 Pre-Deletion

# Warn if uncommitted changes
git status --porcelain | grep -q . && echo "⚠️ Uncommitted changes exist"

4.2 Incremental Deletion

• Delete in batches (5-10 items)
• Verify after each batch
• Stop on first failure

4.3 Post-Deletion Verification

# Must pass after each batch
{build_command}  # npm run build / go build ./...
{test_command}   # npm test / go test ./...
{lint_command}   # npm run lint / golangci-lint run

4.4 Rollback on Failure

git checkout -- {failed_files}

---

Output Format

Final Report

# Dead Code Cleanup Report

**Generated**: {timestamp}
**Scope**: {analyzed_paths}

---

## Summary

| Category        | Count   | Lines       |
| --------------- | ------- | ----------- |
| Unused Exports  | {n}     | {lines}     |
| Deprecated Code | {n}     | {lines}     |
| Orphaned Files  | {n}     | {lines}     |
| **TOTAL**       | **{n}** | **{lines}** |

---

## DELETED (HIGH Confidence)

### {file_path}:{line}

- **Type**: {function/class/variable}
- **Reason**: No references found
- **Verification**: Build ✓ Tests ✓

---

## SKIPPED - Needs Review

### {file_path}:{line}

- **Type**: {function/class/variable}
- **Reason**: {why detected as dead}
- **Skip Reason**: {why preserved}
- **Action**: {recommended next step}

---

## PRESERVED (Matched Rules)

### {file_path}:{line}

- **Rule**: {which preservation rule}
- **Detail**: {specifics}

---

## Verification Results

- Build: {PASS/FAIL}
- Tests: {PASS/FAIL} ({passed}/{total})
- Lint: {PASS/FAIL}

---

Key Rules

Must Do

• Run build + tests after EVERY deletion batch
• Document skip reasons for every preserved item
• Report all skipped items in final summary
• Preserve items matching preservation rules

Must Not Do

• Delete without verification
• Ignore preservation rules
• Skip final report generation
• Batch too many deletions (max 10 per batch)

Safety First

• When uncertain → SKIP and report
• When ambiguous → Ask user
• When build fails → Rollback immediately

---

Example Usage

# Report only (no deletions)
/dead-code-cleanup --dry-run

# Analyze specific directory
/dead-code-cleanup src/legacy/

# Auto-delete HIGH confidence items
/dead-code-cleanup --auto

# Default: interactive mode
/dead-code-cleanup