refactor-cleaner

Refactor & Dead Code Cleaner

Identify and remove dead code, duplicates, and unused exports to keep the codebase lean and maintainable. Safety-first approach with comprehensive documentation.

Related Skills:

• kavak-documentation - Query for Kavak-specific patterns that might look like dead code but are used dynamically
• Use kavak-platform/platform_docs_search MCP tool to verify before removing Kavak SDK/platform code

Quick Start

Detect project type and run appropriate analysis:

Node/TypeScript:

npx knip                    # unused exports/files/deps
npx depcheck                # unused dependencies
npx ts-prune                # unused exports

Go:

go mod tidy                 # remove unused deps
deadcode ./...              # find unreachable code (golang.org/x/tools)
staticcheck ./...           # includes unused code detection

Python:

vulture .                   # find dead code
pip-autoremove              # unused dependencies

Java:

./mvnw dependency:analyze   # unused dependencies
# Use IDE or SpotBugs for dead code detection

Workflow

1. Analysis Phase

Run detection tools and categorize findings:

Risk Level	Examples	Action
SAFE	Unused exports, unused deps	Remove after grep verify
CAREFUL	Dynamic imports possible	Manual review required
RISKY	Public API, shared utils	Do not remove

2. Risk Assessment

For each item to remove:

• Grep for all references (including string patterns)
• Check for dynamic imports
• Verify not part of public API
• Review git history for context

3. Safe Removal Process

a) Start with SAFE items only
b) Remove one category at a time (this order matters — each step
   may reveal more dead code in the next category):
   1. Unused npm/go dependencies (safest, no code changes)
   2. Unused internal exports (removing these may make files unused)
   3. Unused files (now visible after export cleanup)
   4. Duplicate code (consolidate remaining logic)
c) Run tests after each batch
d) Commit each batch separately

4. Document Deletions

Update docs/DELETION_LOG.md after each session:

## [YYYY-MM-DD] Refactor Session

### Removed
- package-name - Reason
- src/unused-file.ts - Replaced by X

### Impact
- Files: -15, Deps: -5, Lines: -2,300

Safety Rules

Before removing ANYTHING:

• Run detection tools
• Grep for all references
• Check dynamic imports
• Run all tests
• Create backup branch

After each removal:

• Build succeeds
• Tests pass
• Commit changes
• Update DELETION_LOG.md

When NOT to Use

• During active feature development
• Right before production deployment
• Without proper test coverage
• On code you don't understand

Error Recovery

# Immediate rollback if something breaks
git revert HEAD

# Reinstall deps and verify (by language)
# Node: npm install && npm run build && npm test
# Go:   go mod download && go build ./... && go test ./...
# Python: pip install -r requirements.txt && pytest
# Java: ./mvnw clean install

Then investigate: Was it a dynamic import/reflection? Update "DO NOT REMOVE" list.

References

Reference	Purpose
references/detection-tools.md	Tool commands and usage
references/safety-checklist.md	Detailed safety procedures
references/deletion-log.md	Log format and examples
references/patterns.md	Common dead code patterns
references/pr-template.md	PR template for cleanup