---
name: unfuck
description: >-
  Comprehensive one-shot repo cleanup skill. This skill should be used when the user asks to
  "clean up the repo", "remove dead code", "de-AI-slop", "unfuck this codebase",
  "comprehensive cleanup", "remove unused code", "simplify the codebase", "fix code quality",
  "clean everything up", "audit the codebase", "fix tech debt", "remove duplicates",
  "unify the architecture", "security review and fix", or wants a thorough, automated cleanup
  of their entire repository. Launches a full agent swarm to discover issues, plan fixes, and
  implement changes autonomously. Combines custom static/semantic analysis with existing
  code-quality review, architecture, security, QA, and simplification agents into a unified
  cleanup workflow.
compatibility: Requires Claude Code with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 for multi-agent orchestration
allowed-tools: Read Write Edit Bash Agent AskUserQuestion SendMessage TaskCreate TaskUpdate TaskList TaskGet LSP Skill
---

# /unfuck — Comprehensive Repo Cleanup

> **Note:** `{skill_dir}` refers to the absolute "Skill directory" path provided in your system instructions.

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.

**Prerequisite:** Agent teams require `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be set in the
environment or `settings.json` — without it, named teammates spawned via `Agent(name=...)` do
not join a shared implicit team and `SendMessage` routing between them will not work.

## 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 `[{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md)`
   (Run-ID Naming Convention section)
2. Spawn parallel setup teammates for: repo indexing (`code-quality:index-repo`), language detection, tool detection (the implicit team is established automatically by these first named teammate spawns — no separate setup call is needed)
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 `[{skill_dir}/references/discovery-agents.md](./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 `[{skill_dir}/references/ai-slop-checklist.md](./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 `[{skill_dir}/references/external-tools.md](./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 `[{skill_dir}/../../references/finding-classification.md](../../references/finding-classification.md)`)
5. Clean up intermediate discovery files
6. 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 `[{skill_dir}/../../references/finding-classification.md](../../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 |
|------|---------|
| `[{skill_dir}/references/orchestration-playbook.md](./references/orchestration-playbook.md)` | Complete phase-by-phase coordination guide with JSON schemas, dedup algorithm, rollback procedures, agent roster config, and error handling |
| `[{skill_dir}/references/discovery-agents.md](./references/discovery-agents.md)` | Full prompts for all 7 discovery agents — role, methodology, external tool commands, LSP patterns, classification/LoE/risk guides, output format |
| `[{skill_dir}/references/implementation-agents.md](./references/implementation-agents.md)` | Full prompts for all 7 implementation agents — fix strategies, paired skills, safety rules, test cadence, commit formats |
| `[{skill_dir}/references/ai-slop-checklist.md](./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 |
| `[{skill_dir}/references/external-tools.md](./references/external-tools.md)` | Tool matrix by language, detection commands, JSON output schemas, parsing instructions, Phase 0 detection script, fallback strategies |