Scoped dead code analysis & cleanup with parallel subagent investigation
Analyzes recent changes to identify dead code, duplicates, and naming issues, then validates findings with parallel subagents.
/plugin marketplace add cahaseler/cc-track/plugin install cc-track@cc-track-marketplacecommit_id: Optional starting commit - analyzes all changes from and including this commit through HEAD plus staged/unstaged/untracked
scope_mode: One of: commit_range, unstaged, spec_branch, context — determines working setanalysis_dir: .cc-track/analysis/spotlessreports_subdir: {analysis_dir}/area_reportsvalidation_subdir: {analysis_dir}/validationsmax_parallel_agents: 4Optional scope specification passed via $ARGUMENTS. If ambiguous, ask user to clarify.
Examples:
/cc-track:spotless abc123 — Analyze from commit abc123 through HEAD/cc-track:spotless unstaged — Analyze staged/unstaged/untracked only/cc-track:spotless spec — Analyze changes on current spec branch vs main/cc-track:spotless context — Analyze files discussed in current sessionIdentify which files to analyze based on arguments or user input.
If arguments contain a commit SHA or ref:
git rev-parse --verify {commit_id}^{commit} 2>/dev/null
git log --name-only --pretty=format: {commit_id}^..HEAD | sort -ugit diff --cached --name-onlygit diff --name-onlygit ls-files --others --exclude-standardElseIf arguments specify "unstaged" or "staged":
git diff --cached --name-onlygit diff --name-onlygit ls-files --others --exclude-standardElseIf arguments specify "spec" or current branch is a spec branch (NNN-feature-name pattern):
git merge-base HEAD main (or master)git diff --name-only $(git merge-base HEAD main)..HEADElseIf arguments specify "context":
Else (scope ambiguous):
mkdir -p .cc-track/analysis/spotless/area_reports
mkdir -p .cc-track/analysis/spotless/validations
mkdir -p .cc-track/analysis/spotless/removal_tasks
Save working set to .cc-track/analysis/spotless/working_set.json:
{
"scope_mode": "commit_range|unstaged|spec_branch|context",
"commit_range": "abc123..HEAD",
"files": ["src/foo.ts", "src/bar.ts"],
"timestamp": "2025-01-01T00:00:00Z"
}
Scan working set files for common dead code indicators.
Patterns to detect (ordered by likelihood after AI changes):
.only, skipped tests, test data that should be removedany to bypass type issuesFor each file in working set: identify potential issues with file:line references.
Group findings by file/module for parallel investigation:
Write to .cc-track/analysis/spotless/initial_findings.md:
Find repeated code patterns in working set.
Patterns to detect:
Output per cluster:
Ignore intentional duplication (test fixtures, generated code).
Identify semantic drift and clarity issues.
Semantic drift (names no longer match expanded scope):
Clarity issues:
data, result, info, item, temp)handle* functions with complex multi-step logicutils.ts, helpers.ts) over 200 linesConvention inconsistency:
get*/fetch*/load* for same operation typehandle*/on* for event handlersWrite to .cc-track/analysis/spotless/duplication_report.md and .cc-track/analysis/spotless/naming_report.md.
Use timestamped variants if files already exist (never overwrite).
Launch parallel investigation agents (up to 4) using the Task tool with subagent_type="general-purpose".
Investigation prompt template:
You are investigating recent changes in {area_name} for dead code artifacts.
**Context**: These files were recently modified. Look for artifacts from failed implementation attempts, abandoned branches, or incomplete refactors.
**Files in scope**: {file_list}
**Initial patterns detected**: {patterns_for_area}
**Your task**:
1. Review all files in scope thoroughly
2. For EACH potential issue, verify:
- Is this code actually unused? (check imports, calls, references)
- Is this a remnant from a failed approach? (check git history if needed)
- Could this break something if removed? (check dependencies)
3. Categorize findings:
- SAFE_TO_REMOVE: Confirmed dead code, no dependencies
- NEEDS_VALIDATION: Likely dead but needs confirmation
- KEEP: Actually used or unclear
4. Document evidence for each finding
**Output format**: Markdown report with sections per issue type.
**Critical**: Be conservative. When in doubt, mark NEEDS_VALIDATION.
Save your report to: .cc-track/analysis/spotless/area_reports/{area_name}_report.md
Wait for all investigation subagents to complete.
Read all investigation reports from .cc-track/analysis/spotless/area_reports/.
Group findings:
Extract high-risk items from SAFE_TO_REMOVE:
For high-risk items, launch validation subagents:
Validation prompt template:
You are validating a finding from dead code analysis.
**Original finding**:
{finding_description}
{file_path}:{line_numbers}
{reasoning_from_investigation}
**Your task**:
1. Search codebase for ANY usage (dynamic imports, string refs, reflection)
2. Check test files for usage
3. Verify the code is actually dead, not just indirectly used
4. Determine: CONFIRMED_SAFE, UNSAFE, or UNCERTAIN
**Output**: Markdown with verdict, evidence, reasoning.
Save to: .cc-track/analysis/spotless/validations/{finding_id}_validation.md
Wait for all validation subagents to complete.
Create final removal list from validation results:
Create .cc-track/analysis/spotless/cleanup_summary.md:
# Dead Code Cleanup Summary
**Scope**: {scope_mode} - {commit_range or description}
**Files Analyzed**: {count}
**Generated**: {timestamp}
## Executive Summary
- Total issues found: X
- Safe to remove: Y
- Manual review required: Z
- Excluded (kept): W
## Safe Removals
| File | Lines | Type | Description |
|------|-------|------|-------------|
| src/foo.ts | 45-67 | Unused function | `oldHelper()` never called |
## Manual Review Required
| File | Lines | Type | Why Review Needed |
|------|-------|------|-------------------|
| src/bar.ts | 12 | Orphaned export | May be dynamically imported |
## Duplication Clusters
{clusters from duplication_report.md}
## Naming Issues
{issues from naming_report.md}
## Excluded Items
| File | Lines | Reason |
|------|-------|--------|
| src/baz.ts | 100-120 | Used via reflection |
For each CONFIRMED_SAFE finding, create .cc-track/analysis/spotless/removal_tasks/task_{id}.md:
# Removal Task: {id}
**Type**: {Unused function | Orphaned file | Dead import | etc.}
**File**: {path}
**Lines**: {start}-{end}
**Evidence**: {why this is confirmed dead}
## Action Required
{Specific removal instructions - delete file, remove lines, etc.}
## Verification
After removal, verify:
- [ ] TypeScript compiles
- [ ] Tests pass
- [ ] No runtime errors
Note: This step only executes when user explicitly approves tasks.
Present summary and ask:
Found X items safe to remove. Review
.cc-track/analysis/spotless/cleanup_summary.mdfor details.Options:
- Execute all safe removals
- Execute specific tasks (provide IDs)
- Review individual tasks first
- Skip execution for now
If user approves:
For each approved task:
.cc-track/analysis/spotless/changes_log.mdAfter all removals:
bunx tsc --noEmitbun testWrite .cc-track/analysis/spotless/execution_report.md: