unfuck

/unfuck — Comprehensive Repo Cleanup

One-shot command that launches a full agent swarm to discover, plan, and fix everything wrong with a codebase: dead code, duplicates, security issues, AI slop, architectural drift, complexity, and documentation rot.

Quick Start

/unfuck                     # Full cleanup of entire repo
/unfuck src/                # Scope to a directory
/unfuck --dry-run           # Discovery + plan only, no implementation

What It Does

Runs a 5-phase workflow combining 12+ existing skills/agents with detailed custom analysis logic and optional external CLI tools. Phase 0 indexes the repo. Phase 1 spawns 7 parallel discovery agents that scan every file. Phase 2 synthesizes findings into a prioritized cleanup plan. Phase 3 spawns sequential implementation agents that fix each category and commit. Phase 4 verifies everything passes and generates a report.

Workflow Phases

Phase 0: Index & Setup

1. Generate a run-ID using the convention in code-quality/references/project-memory-reference.md (Run-ID Naming Convention section)
2. Create TeamCreate swarm: cleanup-{run_id} (using the run ID from step 1)
3. Spawn parallel setup teammates for: repo indexing (code-quality:index-repo), language detection, tool detection
4. Create feature branch: cleanup/comprehensive-{run-id} (from origin/main)
5. Create {memory_dir}/unfuck/{run-id}/discovery/ directory for agent output
6. Collect setup results and build context bundle for discovery agents

Phase 1: Discovery (7 parallel agents)

Phase 1 and Phase 2 use /map-reduce for structured discovery and synthesis — each discovery agent is a mapper, and the synthesis agent is the reducer. This provides formal chunk tracking, retry-on-failure for individual discovery agents, and structured ReductionResult output. If /map-reduce skill is unavailable, fall back to direct parallel agents as described below.

All agents run simultaneously in background. Each writes structured JSON findings to {run_dir}/discovery/. Full prompts in references/discovery-agents.md.

Agent	Role	Paired Skills	External Tools	Output
dead-code-hunter	Unused code, exports, imports, files, deps	file-audit	Knip, Vulture, deadcode	dead-code.json
duplicate-detector	Copy-paste code, near-duplicates, redundant wrappers	file-audit	jscpd	duplicates.json
security-auditor	OWASP Top 10, secrets, CVEs, auth gaps	code-quality:security	Semgrep, gitleaks, Bandit	security.json
architecture-reviewer	Circular deps, divergent patterns, god objects	code-quality:architect	dependency-cruiser, Madge	architecture.json
ai-slop-detector	Over-abstraction, unnecessary wrappers, catch-rethrow, comment noise	(novel — see references/ai-slop-checklist.md)	—	ai-slop.json
complexity-auditor	Long functions, deep nesting, magic values, parameter bloat	code-quality:qa	radon	complexity.json
documentation-auditor	README drift, broken links, stale TODOs, missing docs	file-audit	—	documentation.json

Model note: ai-slop-detector uses opus (detecting AI patterns requires stronger judgment). All others use sonnet.

Tool fallback: When external tools are unavailable, agents perform equivalent analysis manually using LSP, Grep, and file reading. See references/external-tools.md fallback table.

Phase 1.5: External Research Escalation (conditional)

Scan discovery agent findings for references to named third-party libraries or packages (check finding descriptions and affected file paths for import statements, package names, or library-specific API calls). If any findings involve third-party library misuse (e.g., deprecated patterns, non-idiomatic usage, missing security configurations), invoke /deep-research (via the Skill tool) in Bridged mode to research current best practices before planning fixes. This prevents replacing one anti-pattern with another based on stale training data.

Phase 2: Synthesis & Planning

A dedicated opus synthesis teammate (not the orchestrator) performs synthesis to avoid filling the lead agent's context. When using /map-reduce, this agent acts as the reducer — receiving all 7 ChunkResults and producing a ReductionResult before writing the cleanup plan. When falling back to direct approach, it reads the raw discovery JSON files directly.

1. Reads all 7 discovery JSON files (or ChunkResults if /map-reduce was used)
2. Deduplicates overlapping findings across agents (via /map-reduce cross-chunk validation if available, or manual dedup otherwise)
3. Cross-references compound patterns (dead + divergent = safe to remove)
4. Prioritizes: security → dead code → duplicates → AI slop → complexity → architecture → docs
5. Writes {run_dir}/cleanup-plan.md with per-finding detail
6. Creates TaskList with one task per category
7. Sends summary to orchestrator; orchestrator AskUserQuestion if: public API deletions, 5+ file architectural changes, ambiguous findings, security policy decisions, or >100 total findings

Phase 3: Implementation (persistent collaborative team)

A single persistent team of 4 specialists works through all categories sequentially together:

Teammate	Role	Model	Responsibility
impl-writer	Implementer	sonnet	Applies fixes from cleanup plan per category
impl-qa	Reviewer	opus	Reviews changes for correctness, verifies with LSP
impl-tester	Tester	sonnet	Runs test suite and formatters after each category
impl-docs	Documenter	sonnet	Updates documentation affected by code changes

Workflow per category: writer implements → QA reviews → tester verifies → docs updates → commit or rollback. The orchestrator assigns categories in priority order (security → dead code → duplicates → AI slop → complexity → architecture → docs). The team commits after each category passes.

Phase 4: Verification & Report

1. Run full test suite via code-quality:test-runner
2. Run code quality checks on all modified files
3. Apply code-quality:quality-gate verification patterns
4. Invoke code-quality:reflect to verify completeness against the original cleanup plan
5. Generate {run_dir}/cleanup-report.md with:
   • Summary stats (files modified, lines added/removed, net delta, issues fixed by category)
   • Per-category breakdown with specific changes and commit SHAs
   • Blocked items (test failures, needs-input) with stash names and manual fix guidance
   • External tools used vs agent-only analysis
   • Remaining needs-input findings presented to user via AskUserQuestion with LoE (see code-quality/references/finding-classification.md)
6. Clean up intermediate discovery files
7. Report completion to user with summary and report location

Git Workflow

• Creates feature branch: cleanup/comprehensive-{run-id} (from origin/main)
• One commit per cleanup category (security, dead-code, duplicates, ai-slop, complexity, architecture, docs)
• Conventional commit messages
• Blocked categories are stashed with descriptive names for manual recovery

Safety

• Tests verified after every implementation category — rollback on failure
• LSP findReferences before every deletion, move, or rename
• Security fixes NEVER auto-applied if they could change business logic
• AskUserQuestion for all ambiguous or high-risk decisions
• --dry-run flag for discovery + planning without implementation
• Agents use needs-input escape hatch for uncertain changes — see code-quality/references/finding-classification.md Fixer Protocol

Output Files

File	Purpose	Persistent
{run_dir}/cleanup-plan.md	Prioritized findings with fix strategies	Yes
{run_dir}/cleanup-report.md	Final report with stats and blocked items	Yes
{run_dir}/discovery/*.json	Raw agent findings (7 files)	Cleaned up
{run_dir}/available-tools.json	Detected external tools	Cleaned up

References

File	Content
references/orchestration-playbook.md	Complete phase-by-phase coordination guide with JSON schemas, dedup algorithm, rollback procedures, TeamCreate config, and error handling
references/discovery-agents.md	Full prompts for all 7 discovery agents — role, methodology, external tool commands, LSP patterns, classification/LoE/risk guides, output format
references/implementation-agents.md	Full prompts for all 7 implementation agents — fix strategies, paired skills, safety rules, test cadence, commit formats
references/ai-slop-checklist.md	32 anti-patterns across 7 categories (structural, error handling, naming, comments, testing, imports, types) with before/after examples and false-positive guidance
references/external-tools.md	Tool matrix by language, detection commands, JSON output schemas, parsing instructions, Phase 0 detection script, fallback strategies