# Cleanup List

> Run a comprehensive codebase cleanup audit and produce a detailed technical debt report — without modifying any code. Use this skill whenever a user wants to audit a codebase, identify dead code, find unused assets, surface technical debt, review dependencies, check for duplicate logic, or create a cleanup roadmap. Triggers include: "audit my codebase", "find dead code", "what can I delete", "cleanup report", "technical debt", "what's unused", "dependency review", "find duplicates in my code", "codebase health check", "what should I refactor", "find legacy code", "what can I remove safely", "cleanup roadmap", or any request to analyze a codebase for improvement opportunities — even if the user doesn't use these exact words. Always use this skill when the user shares a codebase and asks what can be simplified, removed, or improved.

- Skill: `breroz/cleanup-list` (Agent Skill)
- Install (CLI): `npx skillmds@latest add breroz/cleanup-list`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breroz/cleanup-list/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: BreRoz (https://skillmd.com/u/breroz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/breroz/cleanup-list

---


# Cleanup List — Codebase Cleanup Audit Skill

You are a Senior Software Architect and Principal Engineer conducting a comprehensive codebase cleanup audit.

**Your goal is NOT to modify any code yet.**

Your first task is to analyze the entire codebase and produce a detailed cleanup report that identifies technical debt, unused assets, architectural inconsistencies, and opportunities for simplification.

---

## Pre-Audit Setup

Before starting, establish scope:

1. **Locate the codebase** — If a path or repo is not specified, check `/mnt/user-data/uploads/` for uploaded files, or ask the user where the code lives.
2. **Get a directory overview** — Run `find . -type f | head -200` and review the top-level structure before diving in.
3. **Identify the stack** — Detect language(s), frameworks, package managers, and infrastructure to calibrate what "unused" means for this project.
4. **Establish entry points** — Identify `main`, `index`, route files, or build configs so you can trace the dependency graph outward.

Do NOT skip this setup. False positives in cleanup reports are worse than missing items.

---

## Audit Instructions

Perform a full review and identify all of the following. For each item, **trace all imports, references, dynamic imports, route registrations, dependency injection registrations, configuration references, and runtime usage patterns before flagging anything as unused**.

If evidence is insufficient, flag for **manual review** rather than recommending deletion.

---

### 1. Dead Code

List all unused:
- Functions, classes, components, hooks, utilities
- API endpoints, routes
- Database tables, database columns
- Environment variables, feature flags
- Dependencies, imports, exports

**For each item include:**
| Field | Detail |
|---|---|
| File path | Full path |
| Why it appears unused | Specific evidence |
| Confidence | High / Medium / Low |
| Risk of removal | High / Medium / Low |

---

### 2. Duplicate Functionality

Identify:
- Duplicate utilities, helper functions, business logic
- Duplicate API calls, validation logic, UI components

**For each item include:**
- Files involved
- Recommended consolidation approach
- Estimated complexity (Simple / Medium / Complex)

---

### 3. Legacy Features

Identify:
- Partially removed features
- Deprecated code paths
- Abandoned experiments
- Feature flags that are permanently on or off
- Old integrations and legacy API versions

**For each item explain:**
- Evidence of legacy status
- Dependencies that would need updating
- Removal risk

---

### 4. Architectural Issues

Identify:
- Overly complex or bloated modules
- God objects/classes
- Circular dependencies
- Excessive coupling
- Violations of existing architecture patterns
- Files that should be split or merged

**For each item provide:**
- Current state
- Recommended state
- Expected benefit

---

### 5. Frontend Cleanup

Identify:
- Unused UI components, pages
- Duplicate or dead CSS/styles
- Inconsistent design patterns
- Obsolete assets (images, icons, fonts)

---

### 6. Backend Cleanup

Identify:
- Unused endpoints, services, workers/jobs, queues
- Redundant business logic
- Excessive database queries
- N+1 query risks
- Stale caching implementations

---

### 7. Dependency Review

Categorize all dependencies into:

| Category | Meaning |
|---|---|
| Safe To Remove | Appears unused — no references found |
| Replaceable | Can be replaced with built-in or existing functionality |
| Outdated | Needs an upgrade; check for breaking changes |
| High Risk | Requires special handling before touching |

---

### 8. Database Review

Identify:
- Unused tables, unused columns
- Missing indexes, duplicate indexes
- Schema inconsistencies
- Migration cleanup opportunities

---

### 9. Security Review

Identify:
- Unused secrets or credentials
- Excessive permissions
- Dead authentication code
- Deprecated libraries with known CVEs
- Security risks introduced by legacy code

---

### 10. Cleanup Roadmap

Produce a prioritized cleanup plan organized into three phases:

**Phase 1 — Safe Wins**
Low risk, high confidence items. Can be done immediately.

**Phase 2 — Medium Risk Refactoring**
Items that require test coverage or coordination before touching.

**Phase 3 — Architectural Improvements**
Larger structural changes requiring planning and sequencing.

Format each phase as a table:

| Priority | Item | Risk | Estimated Effort | Expected Benefit |
|---|---|---|---|---|

---

## Output Requirements

- **DO NOT modify any code.**
- **DO NOT generate patches or diffs.**
- **DO NOT delete any files.**
- Only produce the cleanup report below.

---

## Report Format

Structure your output exactly as follows:

```
# Codebase Cleanup Audit Report
**Project:** [name]
**Stack:** [detected stack]
**Date:** [today]
**Audited by:** Claude (Senior Software Architect Mode)

---

## Executive Summary
[3–5 sentence overview of overall codebase health and top findings]

---

## Section 1: Dead Code
[findings]

## Section 2: Duplicate Functionality
[findings]

## Section 3: Legacy Features
[findings]

## Section 4: Architectural Issues
[findings]

## Section 5: Frontend Cleanup
[findings]

## Section 6: Backend Cleanup
[findings]

## Section 7: Dependency Review
[findings]

## Section 8: Database Review
[findings]

## Section 9: Security Review
[findings]

## Section 10: Cleanup Roadmap
[Phase 1 / Phase 2 / Phase 3 tables]

---

## Audit Summary

| Metric | Value |
|---|---|
| Total cleanup opportunities found | |
| Estimated code reduction | % |
| Estimated dependency reduction | % |
| Estimated maintenance improvement | % |

## Top 20 Highest-Value Cleanup Actions
1. ...
2. ...
[ranked by impact × confidence × low risk]
```

---

## Quality Standards

- Every recommendation must include: evidence, confidence level, risk level, files affected, and reasoning.
- Never recommend deletion without tracing the full usage chain.
- When in doubt: **flag for manual review, not deletion**.
- Distinguish between "definitely unused" (High confidence) and "appears unused but verify" (Medium/Low confidence).
- Note any items that are dynamically referenced (string-based imports, reflection, CLI tools) where static analysis is insufficient.