Initial commit

shavakan/cleanup-dead-code.md

@@ -0,0 +1,155 @@
+---
+description: Remove unused imports, functions, variables, commented blocks, unreachable code
+---
+
+# Remove Dead Code
+
+Find and safely remove unused code: imports, functions, variables, commented blocks, unreachable code, unused files.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before cleanup
+3. Backup branch created automatically
+4. Test validation after each removal category
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and remove dead code that clutters the codebase without affecting functionality.
+
+### Categories
+
+**Unused imports** - Modules imported but never referenced
+
+**Unused functions** - Defined but never called, private methods with no references, exported with no external usage
+
+**Unused variables** - Declared but never read, parameters never used, constants not referenced
+
+**Commented code** - 5+ consecutive commented lines with code syntax (belongs in git history)
+
+**Unreachable code** - After return/throw/break, conditional branches that never execute
+
+**Unused files** - Source files with no imports, test files for deleted features, replaced implementations
+
+---
+
+## Execution
+
+### Phase 1: Detect Dead Code
+
+Scan codebase for unused code using language-appropriate static analysis. For each category:
+- Report locations with context
+- Verify findings (check for dynamic references, reflection, callbacks)
+- Count impact (lines that can be removed)
+
+**Be cautious with:**
+- Public API exports - check for external usage first
+- Test utilities - may be needed later even if not currently used
+- Code called dynamically (eval, reflection, event handlers)
+
+**Gate**: User must review findings before removal.
+
+### Phase 2: Confirm Removals
+
+Present findings to user with risk assessment:
+```
+Remove dead code?
+
+□ Safe - Unused imports + variables (auto-fixable)
+□ Low risk - Unused private functions + commented code
+□ Needs review - Unused public functions + unused files
+□ Custom - Select specific items
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to remove.
+
+### Phase 3: Execute Removals
+
+For each approved category:
+
+1. Remove items using language-specific tools when available (eslint --fix, autoflake). For functions/files, manual removal with careful validation.
+
+2. Test and commit: Run `$TEST_CMD` after each category. If passing, commit. If failing, rollback and report which removal broke tests.
+
+3. Continue safely: Process one category at a time. Stop on test failure.
+
+**Gate**: Tests must pass before moving to next category.
+
+### Phase 4: Report Results
+
+Summarize: items removed per category, files affected, lines eliminated, code coverage maintained.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One category at a time with test validation
+- Never remove public API exports without confirming no external usage
+- Verify zero references using code search before removing
+- Test after each removal - rollback on failure
+- Commit granularly
+- Use `git rm` for file removal to preserve history
+- Check for dynamic references (code may be called via string identifiers)
+
+**If tests fail**: Rollback, identify which specific removal caused failure, decide whether to skip that item or investigate why it was actually needed.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify removals don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-comments` - Clean up comments
+- `/shavakan-commands:cleanup-architecture` - Refactor structure