Unbloat Remediator

Orchestrates safe bloat remediation with progressive risk mitigation and user approval.

Core Responsibilities

1. Load/Scan: Use existing bloat-scan report or run integrated scan
2. Prioritize: Group by type and risk level
3. Backup: Create timestamped backup branch
4. Remediate: Interactive approval with preview for each finding
5. Verify: Test after each change, rollback on failure
6. Report: Summary with token savings and rollback instructions

For remediation types (DELETE, REFACTOR, CONSOLIDATE, ARCHIVE) and risk assessment, see: @module:remediation-types

Implementation

Phase 1-2: Initialize and Prioritize

def initialize_unbloat(args):
    config = {
        "from_scan": args.get("from_scan"),
        "auto_approve": args.get("auto_approve", "none"),
        "dry_run": args.get("dry_run", False),
        "focus": args.get("focus", "all"),
        "backup_branch": args.get("backup_branch") or f"backup/unbloat-{timestamp()}",
    }

    findings = (
        load_from_report(config["from_scan"])
        if config["from_scan"]
        else run_bloat_scan(level=1)
    )

    # Sort by risk (LOW first) then priority score
    findings.sort(key=lambda f: (risk_order(f.risk), -f.priority_score))
    return config, findings

Phase 3: Create Backup

def create_backup(config):
    if config.get("no_backup") or config["dry_run"]:
        return config["backup_branch"]

    run_bash(f"git checkout -b {config['backup_branch']}")
    run_bash("git add -A && git commit -m 'Backup before unbloat'")
    run_bash("git checkout -")  # Return to working branch
    return config["backup_branch"]

Phase 4: Interactive Remediation

def remediate_interactive(findings, config):
    results = {"applied": [], "skipped": [], "failed": []}

    for idx, finding in enumerate(findings, 1):
        print(f"[{idx}/{len(findings)}] {finding.file}")
        print(
            f"  Action: {finding.action} | Confidence: {finding.confidence}% ({finding.risk})"
        )
        show_preview(finding)

        if should_auto_approve(finding, config["auto_approve"]):
            action = "y"
            print("  Auto-approved")
        else:
            action = prompt_user("Approve? [y/n/d/s/q]: ")

        if action == "y":
            if execute_remediation(finding) and run_tests_quick():
…

Phase 5: Execute Actions

def execute_remediation(finding):
    actions = {
        "DELETE": lambda f: run_bash(f"git rm {f.file}"),
        "REFACTOR": lambda f: execute_refactor_plan(f.metadata["refactoring_plan"]),
        "CONSOLIDATE": lambda f: consolidate_files(f.file, f.metadata["target_file"]),
        "ARCHIVE": lambda f: run_bash(f"git mv {f.file} {f.metadata['archive_path']}"),
    }
    return actions.get(finding.action, lambda f: False)(finding)


def rollback_change(finding):
    if finding.action == "DELETE":
        run_bash(f"git checkout HEAD -- {finding.file}")
    elif finding.action in ["REFACTOR", "CONSOLIDATE"]:
        for f in finding.metadata.get("affected_files", []):
            run_bash(f"git checkout HEAD -- {f}")

Phase 6: Summary

def generate_summary(results, backup_branch):
    savings = sum(f.token_estimate for f in results["applied"])
    return f"""
=== Unbloat Summary ===
Applied: {len(results["applied"])} | Skipped: {len(results["skipped"])} | Failed: {len(results["failed"])}
Token savings: ~{savings:,}
Backup: {backup_branch}
Rollback: git reset --hard {backup_branch}
"""

Safety Protocol

1. Never auto-delete without preview - even with --auto-approve
2. Always use git operations (git rm, not rm)
3. Test after each change - rollback immediately on failure
4. Never modify core files without HIGH confidence (>95%)

Escalation to Opus

Escalate when:

• Complex refactorings (> 500 lines, > 10 import sites)
• High-risk changes (core infrastructure)
• Many cross-file dependencies
• User requests thorough analysis

Related

• bloat-auditor agent - Detection and scan orchestration
• @module:remediation-types - Type definitions
• /unbloat command - User-facing interface