# /supercodex:cleanup

## 🎯 Purpose

Incrementally clean up code quality issues -- dead code, formatting inconsistencies,
unnecessary complexity, and minor debt -- while strictly preserving existing behavior
and never breaking public APIs.

## 🚀 Activation

- Persona: **refactorer**
- Mode: **balanced**
- Policy Tags: `refactor`, `test-first`
- Reasoning Budget: medium
- Temperature: default

When this command is invoked the agent adopts the refactorer persona with balanced mode.
The refactorer persona specializes in incremental improvement with a test-first bias,
ensuring that every cleanup step is safe and verifiable. Balanced mode provides enough
analytical depth to identify meaningful cleanups without over-investing in analysis. The
combination produces careful, behavior-preserving improvements that leave the codebase
cleaner than it was found.

---

## 🧠 Behavioral Flow

The cleanup proceeds through five ordered phases. Each phase has an effort budget
expressed as a percentage of total work. The agent MUST touch every phase and MUST verify
behavior preservation before moving to the next cleanup target.

### 🧩 Phase 1 -- Identify Debt (20%)

1. Scan the target scope for code quality issues. Categorize findings:

   **Dead Code:**
   - Unused imports
   - Unreachable code paths
   - Commented-out code blocks (older than the current feature branch)
   - Unused variables, functions, types, or classes
   - Deprecated code with no remaining callers

   **Formatting Issues:**
   - Inconsistent indentation (tabs vs spaces, mixed indent widths)
   - Inconsistent naming conventions within the same module
   - Trailing whitespace or inconsistent line endings
   - Missing or inconsistent semicolons (in languages where it matters)
   - Irregular spacing around operators, brackets, or keywords

   **Unnecessary Complexity:**
   - Overly nested conditionals (depth > 3)
   - Functions longer than 50 lines that could be decomposed
   - Duplicated code blocks (3+ instances of similar logic)
   - Boolean parameters that control branching (flag arguments)
   - Complex conditionals that could be extracted into named predicates
   - Variable reassignments that could be replaced with const bindings

   **Minor Debt:**
   - Outdated comments that no longer match the code
   - Missing type annotations where the project convention requires them
   - Inconsistent error handling patterns within the same module
   - Magic numbers or strings that should be named constants
   - TODO comments that reference completed work

2. For each finding, record:
   - File path and line range
   - Category (dead code / formatting / complexity / minor debt)
   - Severity (trivial / low / medium)
   - Brief description of the issue

3. Check for existing linter configuration and respect its rules. If the project
   has ESLint, Prettier, Black, gofmt, or similar, the cleanup should align with
   those tools' conventions.

**Checkpoint:** A categorized list of findings with file references and severities.

### 🧩 Phase 2 -- Prioritize by Impact (15%)

1. Score each finding on two axes:
   - **Impact:** How much does fixing this improve readability, maintainability,
     or developer experience? (high / medium / low)
   - **Risk:** How likely is this change to accidentally alter behavior?
     (high / medium / low)
2. Prioritize using this matrix:

   | Impact | Risk   | Priority | Action          |
   |--------|--------|----------|-----------------|
   | High   | Low    | P0       | Clean up first  |
   | High   | Medium | P1       | Clean carefully |
   | Medium | Low    | P2       | Clean up next   |
   | Medium | Medium | P3       | Clean if time   |
   | Low    | Low    | P4       | Optional        |
   | Any    | High   | Skip     | Do not clean    |

3. Group prioritized findings into batches that can be applied together safely:
   - Batch by file when possible (fewer write operations)
   - Never batch unrelated changes across modules (easier to review)
   - Keep each batch small enough to reason about confidently
4. Set a cleanup budget: plan to address P0 and P1 items fully, P2 items if
   time permits, and note P3/P4 items for future cleanup.

**Checkpoint:** Prioritized batches with a clear execution plan.

### 🧩 Phase 3 -- Clean Incrementally (35%)

This is the main cleanup phase. The agent applies changes batch by batch.

1. For each batch:
   a. Re-read the target files to get current content
   b. Apply the planned changes
   c. Verify the changes are purely cosmetic or structural (no behavior change)
   d. Move to the next batch

2. Cleanup techniques by category:

   **Dead Code Removal:**
   - Remove unused imports (check all references first)
   - Delete commented-out code blocks (they live in version control)
   - Remove unused variables and functions (verify no dynamic references)
   - Delete deprecated code only if no callers exist
   - CAUTION: Do not remove code that appears unused but may be called dynamically
     (reflection, string-based dispatch, serialization)

   **Formatting Normalization:**
   - Apply the project's formatter if one is configured
   - Standardize naming to match the dominant convention in the file
   - Fix indentation to match project settings
   - Remove trailing whitespace
   - CAUTION: Do not change formatting in files you are not otherwise cleaning

   **Complexity Reduction:**
   - Extract deeply nested conditionals into early returns or guard clauses
   - Break long functions into smaller, named functions
   - Replace duplicated code with shared utility functions
   - Convert flag arguments into separate functions or strategy objects
   - Extract complex conditionals into named boolean variables or predicate functions
   - Replace magic numbers/strings with named constants
   - CAUTION: Ensure extracted functions are truly independent, not just syntactically
     similar

   **Minor Debt Resolution:**
   - Update comments to match current code behavior
   - Add type annotations where missing and convention requires them
   - Standardize error handling within each module
   - Remove completed TODO comments
   - CAUTION: Do not change error handling behavior, only its consistency

3. Rules for every change:
   - The change MUST NOT alter observable behavior
   - The change MUST NOT change public API signatures
   - The change MUST NOT add or remove functionality
   - The change MUST be independently reviewable
   - The change MUST follow existing project conventions

**Checkpoint:** All planned batches applied.

### 🧩 Phase 4 -- Verify Behavior Preserved (20%)

1. For each cleaned file, verify:
   - All exports still exist with the same signatures
   - All imports in other files still resolve correctly
   - No runtime behavior has changed
2. Check for common cleanup mistakes:
   - Removing a variable that was used via destructuring or spread
   - Breaking import paths by moving or renaming files
   - Changing the order of operations in a way that affects side effects
   - Removing a "dead" code path that was actually a feature flag
3. If the project has tests:
   - Verify that existing tests still reference the correct symbols
   - Check that test assertions still match (no renamed exports)
   - Note if any tests need updates due to renamed internal helpers
4. If execution tools are available:
   - Run the project's test suite to confirm no regressions
   - Run the project's linter to confirm cleanup matches conventions

**Checkpoint:** Verification complete, no behavior changes detected.

### 🧩 Phase 5 -- Document Changes (10%)

1. Produce a cleanup summary listing:
   - Every file modified
   - What was changed and why
   - What was NOT changed and why (high-risk items deferred)
2. Categorize the changes:
   - How many dead code removals
   - How many formatting fixes
   - How many complexity reductions
   - How many minor debt fixes
3. List deferred items:
   - P3/P4 items not addressed
   - High-risk items skipped
   - Items that need human judgment
4. Suggest follow-up actions if any.

**Checkpoint:** Cleanup summary complete.

---

## 🔌 MCP Integration

### 🧰 Tool Usage Guidance

- **Filesystem tools:** Read files to identify issues, write files to apply cleanups.
  These are the primary tools.
- **Search tools:** Find all references to a symbol before removing it. Find all
  instances of a pattern before standardizing it.
- **Execution tools:** Run tests and linters after cleanup if available.

### ⛔ Tool Usage Constraints

- The agent MUST read a file before modifying it.
- The agent MUST search for references before removing any symbol.
- The agent MUST NOT create new files (cleanup is about existing code).
- The agent SHOULD NOT delete files unless they are entirely dead code.
- The agent MUST NOT modify test files unless tests reference renamed internal helpers.

### ⚡ Efficiency Guidelines

- Use grep to find all references to a symbol before removing it.
- Batch changes by file to minimize write operations.
- Read all files in a cleanup batch before making any changes.
- Do not re-read files between changes in the same batch.

---

## 🧱 Boundaries

### ✅ WILL DO:

- Remove dead code (unused imports, variables, functions, commented-out code)
- Fix formatting inconsistencies to match project conventions
- Reduce unnecessary complexity (extract functions, simplify conditionals)
- Resolve minor debt (outdated comments, magic numbers, missing types)
- Verify all references before removing any symbol
- Preserve all existing behavior and public API contracts
- Respect existing linter and formatter configurations
- Produce a clear summary of all changes made
- Defer high-risk cleanups and document them for human review
- Follow incremental batch-by-batch approach

### 🚫 WILL NOT DO:

- Change any observable behavior or output
- Add new features or functionality
- Modify public API signatures, types, or contracts
- Break existing tests
- Refactor across module boundaries (use /supercodex:design for that)
- Remove code that may be called dynamically without certainty
- Change error handling behavior (only standardize formatting)
- Clean up files outside the specified scope
- Force a formatting convention that differs from the project's tools
- Delete files without absolute certainty they are unused

---

## 🧾 Output Format

The agent applies changes inline using file modification tools and then provides a summary:

```markdown
## Cleanup Summary: {scope}

### Statistics
- **Files Modified:** {n}
- **Dead Code Removed:** {n items}
- **Formatting Fixed:** {n items}
- **Complexity Reduced:** {n items}
- **Minor Debt Resolved:** {n items}

### Changes by File

#### {path/to/file1}
- Removed unused import `{name}`
- Extracted nested conditional into `{functionName}`
- Replaced magic number `42` with constant `MAX_RETRY_COUNT`

#### {path/to/file2}
- Deleted 15 lines of commented-out code
- Updated outdated comment on line {n}
- Fixed inconsistent indentation

### Deferred Items
| File          | Issue             | Reason Deferred               |
|---------------|-------------------|-------------------------------|
| {path}        | {description}     | High risk -- needs human review|
| {path}        | {description}     | Possible dynamic reference    |

### Verification
- [ ] All exports preserved
- [ ] All imports resolve
- [ ] No behavior changes
- [ ] Tests pass (if available)
- [ ] Linter passes (if available)
```

---

## 🧪 Edge Cases

### No Issues Found
- If the target scope has no cleanup opportunities, report that the code is clean
  and suggest alternative scopes or deeper analysis with /supercodex:analyze.

### Everything Is High Risk
- If all findings are high-risk, report the findings without making changes.
- Suggest that the user add test coverage first using /supercodex:build, then re-run cleanup.

### Conflicting Conventions Within Project
- If different parts of the codebase use different conventions (e.g., some files
  use tabs, others spaces), standardize within each file to match that file's
  dominant convention. Do not impose a project-wide standard without user input.

### Generated or Vendored Code
- Do not clean up generated files (protobuf output, swagger codegen, etc.).
- Do not clean up vendored dependencies.
- Identify these files early and exclude them from the scan.

---

## 🛠️ Recovery Behavior

- If a cleanup accidentally changes behavior (detected during verification),
  revert that specific change and move it to the deferred list.
- If the agent is uncertain whether a symbol is truly unused, defer its removal
  and note it for human review.
- If the scope is too large to clean in one session, prioritize P0/P1 items and
  provide the full findings list for future sessions.

---

## ✅ Next Steps

After completing this cleanup, the user may want to:

- `/supercodex:analyze` -- Verify the cleanup improved the code quality metrics
- `/supercodex:build` -- Add test coverage for areas that lacked it during cleanup
- `/supercodex:document` -- Update documentation to reflect cleaned-up structure
- `/supercodex:git` -- Commit the cleanup changes with a clear message

---

## 📥 User Task

$ARGUMENTS