Safe bloat remediation: delete dead code, consolidate duplicates, refactor large files with user approval. Triggers: unbloat, remove bloat, cleanup codebase, reduce bloat Use when: after bloat-scan or preparing for release
Safe bloat remediation with user approval at each step. Use after bloat-scan or before releases to delete dead code, consolidate duplicates, and refactor large files.
/plugin marketplace add athola/claude-night-market/plugin install conserve@claude-night-marketExecute safe bloat remediation workflows with user approval at each step.
Safety First: Every deletion, refactoring, or merge requires explicit approval. No automatic changes without review.
Progressive Remediation: Start with high-confidence, low-risk changes first. Build confidence before tackling complex refactorings.
Reversible Actions: Create backup branches, detailed git history, and provide rollback instructions.
# Integrated workflow: scan + remediate
/unbloat
# Use existing bloat-scan report
/unbloat --from-scan bloat-report-2025-12-31.md
# Auto-approve low-risk changes (still shows preview)
/unbloat --auto-approve low
# Preview changes without executing
/unbloat --dry-run
# Focus on specific area
/unbloat --focus code
/unbloat --focus docs
/unbloat --focus deps
| Option | Description | Default |
|---|---|---|
--from-scan <file> | Use existing bloat-scan report | Run new scan |
--auto-approve <level> | Auto-approve: low, medium, none | none |
--dry-run | Preview all changes without executing | false |
--focus <area> | Focus: code, docs, deps, or all | all |
--backup-branch <name> | Custom backup branch name | backup/unbloat-{date} |
--no-backup | Skip backup branch creation | false (always backup) |
# If --from-scan provided
if [ -f "$SCAN_REPORT" ]; then
load_findings_from_report "$SCAN_REPORT"
else
# Run integrated Tier 1 scan
findings=$(run_bloat_scan --level 1 --focus "$FOCUS")
fi
Group findings by remediation type and risk level:
Type Categories:
Risk Levels:
# Always create backup before any changes
git checkout -b backup/unbloat-$(date +%Y%m%d-%H%M%S)
git add -A
git commit -m "Backup before unbloat operation"
# Return to working branch
git checkout -
# Save backup branch name for rollback instructions
BACKUP_BRANCH=$(git branch --list 'backup/unbloat-*' | tail -1)
For each finding, in priority order:
def remediate_finding(finding):
"""
Interactive remediation with user approval
"""
# 1. Show finding details
display_finding_summary(finding)
# 2. Show proposed action
display_proposed_action(finding)
# 3. Show preview (diff, content sample, impact)
show_preview(finding)
# 4. Request approval (unless auto-approved)
if not auto_approved(finding):
action = prompt_user(
"Action? [y]es / [n]o / [d]iff / [s]kip rest / [q]uit: "
)
else:
action = 'y'
print("Auto-approved (low risk)")
# 5. Execute based on response
if action == 'y':
execute_remediation(finding)
record_action('APPLIED', finding)
elif action == 'd':
show_detailed_diff(finding)
return remediate_finding(finding) # Re-prompt
elif action == 's':
return 'SKIP_REST'
elif action == 'q':
return 'QUIT'
else:
record_action('SKIPPED', finding)
return 'CONTINUE'
After each change:
# Run tests if available
if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
make test --quiet
elif [ -f "package.json" ] && grep -q "\"test\"" package.json; then
npm test --silent
elif [ -f "pytest.ini" ] || [ -f "tests/" ]; then
pytest --quiet
fi
# Verify build still works
if [ -f "Makefile" ] && grep -q "^build:" Makefile; then
make build --quiet
fi
=== Unbloat Summary ===
Started: 2025-12-31T02:15:00Z
Completed: 2025-12-31T02:47:00Z
Duration: 32m
ACTIONS TAKEN:
Deleted: 5 files
Refactored: 2 files
Consolidated: 3 files
Archived: 1 file
Skipped: 13 findings
TOKEN SAVINGS:
Estimated: ~31,500 tokens
Realized: ~28,200 tokens (89% of estimate)
CONTEXT REDUCTION:
Before: 45% utilization
After: 33% utilization
Reduction: 12 percentage points
FILES CHANGED:
- src/deprecated/old_handler.py (DELETED)
- src/legacy/stale_module.py (DELETED)
- docs/archive/old-setup.md (CONSOLIDATED → docs/setup.md)
- src/utils/helpers.py (REFACTORED → src/utils/{auth,validation,format}.py)
TESTS:
Status: PASSED ✓
Duration: 2m 14s
BACKUP:
Branch: backup/unbloat-20251231-021500
Restore: git checkout backup/unbloat-20251231-021500
NEXT STEPS:
1. Review changes: git diff HEAD~11
2. Commit changes: git add -A && git commit -m "Unbloat: reduce codebase by 14%"
3. Run full test suite: make test
4. If satisfied: git branch -D backup/unbloat-20251231-021500
5. If issues: git reset --hard backup/unbloat-20251231-021500
When Applied:
Example:
Finding: src/deprecated/old_handler.py
Score: 95/100
Confidence: HIGH (92%)
Proposed Action: DELETE
Rationale: 0 references, stale 22mo, 100% dead (Vulture)
Preview:
File size: 847 lines (~3,200 tokens)
Last modified: 2023-02-15
References: None found
Command: git rm src/deprecated/old_handler.py
Approve deletion? [y/n/d/s/q]: _
When Applied:
Example:
Finding: src/utils/helpers.py
Score: 82/100
Confidence: MEDIUM (76%)
Proposed Action: REFACTOR (split into modules)
Rationale: 634 lines, 18 methods, 4 distinct responsibilities
Preview:
Current: src/utils/helpers.py (634 lines)
Proposed split:
→ src/utils/auth.py (147 lines, 4 methods)
→ src/utils/validation.py (212 lines, 7 methods)
→ src/utils/formatting.py (189 lines, 5 methods)
→ src/utils/misc.py (86 lines, 2 methods)
Import updates required: 23 files
Approve refactoring? [y/n/d/s/q]: _
When Applied:
Example:
Finding: docs/archive/old-setup-guide.md
Score: 88/100
Confidence: HIGH (89%)
Proposed Action: CONSOLIDATE
Rationale: 91% similar to docs/setup.md, content superseded
Preview:
Target: docs/archive/old-setup-guide.md (324 lines)
Destination: docs/setup.md
Similarity: 91% (295/324 lines match)
Unique content (29 lines):
- Legacy installation steps (lines 45-58)
- Deprecated configuration (lines 102-116)
Action:
1. Review unique sections
2. Preserve valuable content in setup.md
3. Delete old-setup-guide.md
Approve consolidation? [y/n/d/s/q]: _
When Applied:
Example:
Finding: examples/legacy-tutorial.md
Score: 71/100
Confidence: MEDIUM (68%)
Proposed Action: ARCHIVE
Rationale: Outdated tutorial, historical value, few references
Preview:
Source: examples/legacy-tutorial.md
Destination: docs/archive/legacy-tutorial.md
References: 2 found (README.md mentions it)
Action:
1. Move to docs/archive/
2. Update README.md reference
3. Add deprecation notice in file
Approve archiving? [y/n/d/s/q]: _
--auto-approve lowAuto-approves findings that meet ALL criteria:
Still shows preview, just skips manual approval prompt.
--auto-approve mediumAuto-approves LOW + findings that meet:
Use with caution - review summary before committing.
--auto-approve none (default)Prompts for every single change. Safest option.
# Before any changes
git checkout -b backup/unbloat-$(date +%Y%m%d-%H%M%S)
git add -A
git commit -m "Backup before unbloat"
git checkout -
# Every deletion is a git operation
git rm <file> # Not rm <file>
# Can be restored
git checkout HEAD -- <file>
# Verify nothing broke
make test --quiet
# If tests fail, immediately revert
git checkout HEAD -- <changed-files>
# Log every action to .unbloat-log
echo "$(date) | DELETE | src/old.py | Approved" >> .unbloat-log
echo "$(date) | REFACTOR | src/helpers.py | Skipped" >> .unbloat-log
Always provide clear rollback steps:
# If anything goes wrong
git reset --hard <backup-branch>
# Or restore specific file
git checkout <backup-branch> -- path/to/file
# Two-step workflow (recommended)
/bloat-scan --level 2 --report bloat-report.md
# Review report, plan approach
/unbloat --from-scan bloat-report.md
# Integrated workflow (faster)
/unbloat # Runs Tier 1 scan internally
# Check context before/after
/context-status
/unbloat
/context-status # See reduction
# Combine with other optimization
/unbloat --focus code
/optimize-context # Further optimize remaining code
# Clean branch workflow
git checkout -b cleanup/unbloat-Q1-2025
/unbloat
make test
/pr "Unbloat: Reduce codebase by 14%, save 28k tokens"
$ /unbloat
🧹 Starting unbloat workflow...
Phase 1: Scanning for bloat (Tier 1, quick scan)
[████████████████████] 847 files scanned (4.2s)
✅ Found 24 bloat items
Phase 2: Creating backup branch
✅ Backup created: backup/unbloat-20251231-021500
Phase 3: Prioritizing findings
- 5 HIGH confidence deletions
- 3 MEDIUM confidence refactorings
- 2 Documentation consolidations
Phase 4: Remediation (interactive)
[1/10] src/deprecated/old_handler.py
Action: DELETE
Confidence: 95% (HIGH)
Impact: ~3,200 tokens
Rationale: 0 refs, stale 22mo, 100% dead code
Preview (first 10 lines):
1 # This module is deprecated
2 # TODO: Remove after migration complete
3
4 def old_handler(request):
...
Approve deletion? [y/n/d/s/q]: y
✅ Deleted src/deprecated/old_handler.py
Running tests... ✅ PASSED
[2/10] docs/archive/old-setup.md
Action: CONSOLIDATE
Confidence: 89% (HIGH)
Impact: ~2,400 tokens
...
Approve consolidation? [y/n/d/s/q]: y
✅ Consolidated into docs/setup.md
✅ Deleted docs/archive/old-setup.md
[3/10] src/utils/helpers.py
Action: REFACTOR
Confidence: 76% (MEDIUM)
Impact: ~2,800 tokens
...
Approve refactoring? [y/n/d/s/q]: n
⏭️ Skipped
...
Phase 5: Summary
=== Unbloat Complete ===
Actions: 7 applied, 3 skipped
Token savings: ~18,400 tokens (65% of estimate)
Context reduction: 8 percentage points
Duration: 18m 32s
Backup: backup/unbloat-20251231-021500
Tests: PASSED ✓
Next steps:
1. Review: git diff HEAD~7
2. Commit: git add -A && git commit -m "Unbloat: 7 deletions/consolidations"
3. Clean backup: git branch -D backup/unbloat-20251231-021500
$ /bloat-scan --level 2 --report audit.md
# Review audit.md, identify priorities
$ /unbloat --from-scan audit.md --focus code
🧹 Loading findings from audit.md...
✅ Loaded 24 findings, filtering for code bloat...
📋 Processing 15 code-related findings
[1/15] src/deprecated/old_api.py
...
$ /unbloat --auto-approve low
🧹 Starting unbloat (auto-approve: low-risk only)...
Phase 4: Remediation
[1/10] src/deprecated/old_handler.py
Action: DELETE
Confidence: 95% (HIGH)
Auto-approved ✓
✅ Deleted (3,200 tokens saved)
[2/10] src/utils/helpers.py
Action: REFACTOR
Confidence: 76% (MEDIUM)
Requires manual approval
Approve refactoring? [y/n/d/s/q]: _
$ /unbloat --dry-run
🧹 Unbloat Preview (DRY RUN - no changes will be made)
Phase 4: Remediation Preview
[1/10] src/deprecated/old_handler.py
Action: DELETE
Impact: ~3,200 tokens
Status: WOULD DELETE ⚠️
[2/10] src/utils/helpers.py
Action: REFACTOR
Impact: ~2,800 tokens
Status: WOULD REFACTOR ⚠️
...
Summary (DRY RUN):
Would delete: 5 files
Would refactor: 2 files
Would consolidate: 3 files
Total token savings: ~28,400 tokens
To execute: /unbloat (remove --dry-run flag)
# If tests fail after a change
❌ Tests failed after deleting src/old.py
Rolling back...
git checkout HEAD -- src/old.py
✅ Restored src/old.py
⚠️ Marked as SKIP, continuing with remaining findings
# If build breaks
❌ Build failed after refactoring src/helpers.py
Rolling back refactoring...
git checkout HEAD -- src/helpers.py src/utils/
✅ Restored files
⚠️ Marked as SKIP
# User presses Ctrl+C or chooses 'q'
⚠️ Unbloat interrupted by user
Summary (partial):
Completed: 3/10 findings
Applied: 2 changes
Skipped: 1 change
Remaining: 7 findings
Backup: backup/unbloat-20251231-021500
To resume: /unbloat --from-scan .unbloat-progress.yaml
To rollback: git reset --hard backup/unbloat-20251231-021500
# Run scan first, review findings
/bloat-scan --level 2 --report findings.md
# Review findings.md carefully
# Then execute remediation
/unbloat --from-scan findings.md
# First time: low-risk only
/unbloat --auto-approve low
# Build confidence: expand to medium
/unbloat --auto-approve medium
# Expert mode: full interactive
/unbloat
# After unbloat, run full test suite
/unbloat
make test # Full suite, not just quick tests
make build
# Don't commit all changes at once
git add src/deprecated/
git commit -m "Remove deprecated modules (unbloat 1/3)"
git add docs/archive/
git commit -m "Consolidate duplicate docs (unbloat 2/3)"
git add src/utils/
git commit -m "Refactor utils into focused modules (unbloat 3/3)"
Check .unbloat-log to see what changed:
cat .unbloat-log | grep APPLIED
# Rollback specific change
git checkout HEAD -- path/to/problematic-file
Restore from backup:
git checkout backup/unbloat-YYYYMMDD-HHMMSS -- path/to/file
# Find backup branch
git branch --list 'backup/unbloat-*'
# Reset to backup
git reset --hard backup/unbloat-YYYYMMDD-HHMMSS
/bloat-scan - Detect bloat before remediationbloat-detector skill - Detection patterns and algorithmsbloat-auditor agent - Scan orchestrationcontext-optimization skill - Further optimization after unbloat/optimize-context - Optimize remaining codebase