/refactor-clean

name: refactor-clean
description: Safely identify and remove dead code with test verification at every step. Use when Codex needs to clean unused exports, files, dependencies, helpers, wrappers, re-exports, or duplicate code without risking regressions. Trigger for dead-code cleanup, unused dependency audits, stale utility removal, cleanup refactors, or requests to reduce code safely before or alongside maintenance work.

Refactor Clean

Use a conservative cleanup loop. Prefer keeping uncertain code over deleting something with hidden runtime or external consumers.

Workflow

1. Establish a baseline. 2. Detect dead code with language-appropriate tools. 3. Categorize findings into `SAFE`, `CAUTION`, or `DANGER`. 4. Remove one `SAFE` item at a time. 5. Re-run verification after every deletion. 6. Investigate `CAUTION` items before touching them. 7. Skip `DANGER` items unless the user explicitly wants deeper investigation. 8. Consolidate obvious duplicates only after dead-code cleanup is stable.

Establish A Baseline

• Run the smallest meaningful baseline first, then the broader project checks required by the repo.
• Record whether the suite already fails before cleanup starts.
• Do not treat newly discovered pre-existing failures as caused by the cleanup.
• If the baseline is red in the target area, pause and tell the user before deleting code.

Detect Dead Code

Choose tools by ecosystem. Prefer the project's package manager and existing scripts where possible.

| Tool | What it finds | Command | | --- | --- | --- | | `knip` | Unused exports, files, dependencies | `npx knip` | | `depcheck` | Unused npm dependencies | `npx depcheck` | | `ts-prune` | Unused TypeScript exports | `npx ts-prune` | | `vulture` | Unused Python code | `vulture src/` | | `deadcode` | Unused Go code | `deadcode ./...` | | `cargo-udeps` | Unused Rust dependencies | `cargo +nightly udeps` |

If specialized tooling is unavailable, fall back to targeted search:

• Find exported symbols and files.
• Search for imports, requires, dynamic imports, route references, config references, and string-based lookups.
• Treat "zero obvious references" as a lead, not proof.

Categorize Findings

Assign every finding to a safety tier before editing.

| Tier | Typical examples | Default action | | --- | --- | --- | | `SAFE` | Unused internal utilities, private helpers, unused tests/helpers, wrapper functions with no callers | Delete with verification | | `CAUTION` | Components, hooks, API routes, middleware, server actions, jobs, CLI commands | Investigate runtime and indirect usage first | | `DANGER` | Config files, entry points, exported types, schema files, generated boundaries, public APIs | Skip unless the user asks for deeper work |

Escalate to a higher-risk tier when any of these are present:

• Dynamic import paths
• Reflection or registry lookups
• String-based routing or command dispatch
• Framework auto-discovery
• Package public exports
• External consumers or cross-repo usage

Safe Deletion Loop

For each `SAFE` item:

1. Run the baseline verification. 2. Delete exactly one item with a surgical edit. 3. Re-run the relevant tests immediately. 4. If tests fail, restore the deletion and skip the item. 5. If tests pass, continue to the next item.

Keep deletions atomic. Do not batch multiple unrelated removals into a single verification cycle.

If a revert is needed:

• Restore only the item under test.
• Prefer non-destructive restore methods that do not disturb unrelated user changes.
• Note the failure in the summary and move on.

Handle Caution Items

Before deleting a `CAUTION` item, explicitly check for:

• `import()` or `require()` usage
• String references in configs, routes, registries, feature flags, and tests
• Re-exports from package or app entry points
• External consumers if the module is part of a published or shared surface
• Framework conventions that auto-load files by name or location

Delete a `CAUTION` item only when indirect usage has been ruled out and verification still passes.

Consolidate Duplicates

After dead-code removals are green, look for low-risk consolidation:

• Near-duplicate functions with the same behavior
• Redundant type definitions
• Pass-through wrappers that add no policy or ergonomics
• Re-exports that add no discoverability or compatibility value

Keep this phase separate from dead-code deletion. If consolidation changes behavior, stop treating it as cleanup and call it out explicitly.

Reporting

End with a short cleanup report that includes:

• Deleted functions, files, and dependencies
• Skipped items and why
• Approximate lines removed
• Verification commands run
• Final pass/fail state

Use this format when it helps:

Dead Code Cleanup
----------------------------
Deleted:   12 unused functions
           3 unused files
           5 unused dependencies
Skipped:   2 items (verification failed)
Saved:     ~450 lines removed
----------------------------
All tests passing

Rules

• Never delete code before running a baseline verification step.
• Remove one item at a time.
• Skip uncertain findings instead of guessing.
• Do not mix broad refactors into the deletion loop.
• Preserve unrelated user changes while restoring failed deletions.
• Be explicit about residual risk when `CAUTION` or `DANGER` items remain.