Refactor Clean
Use a conservative cleanup loop. Prefer keeping uncertain code over deleting something with hidden runtime or external consumers.
Workflow
- Establish a baseline.
- Detect dead code with language-appropriate tools.
- Categorize findings into
SAFE, CAUTION, or DANGER.
- Remove one
SAFE item at a time.
- Re-run verification after every deletion.
- Investigate
CAUTION items before touching them.
- Skip
DANGER items unless the user explicitly wants deeper investigation.
- 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:
- Run the baseline verification.
- Delete exactly one item with a surgical edit.
- Re-run the relevant tests immediately.
- If tests fail, restore the deletion and skip the item.
- 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.
1---
2name: refactor-clean
3description: 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.
4metadata:
5 source: https://skillmd.com/skills/julianromli/refactor-clean
6---
7
8# Refactor Clean
9
10Use a conservative cleanup loop. Prefer keeping uncertain code over deleting something with hidden runtime or external consumers.
11
12## Workflow
13
141. Establish a baseline.
152. Detect dead code with language-appropriate tools.
163. Categorize findings into `SAFE`, `CAUTION`, or `DANGER`.
174. Remove one `SAFE` item at a time.
185. Re-run verification after every deletion.
196. Investigate `CAUTION` items before touching them.
207. Skip `DANGER` items unless the user explicitly wants deeper investigation.
218. Consolidate obvious duplicates only after dead-code cleanup is stable.
22
23## Establish A Baseline
24
25- Run the smallest meaningful baseline first, then the broader project checks required by the repo.
26- Record whether the suite already fails before cleanup starts.
27- Do not treat newly discovered pre-existing failures as caused by the cleanup.
28- If the baseline is red in the target area, pause and tell the user before deleting code.
29
30## Detect Dead Code
31
32Choose tools by ecosystem. Prefer the project's package manager and existing scripts where possible.
33
34| Tool | What it finds | Command |
35| --- | --- | --- |
36| `knip` | Unused exports, files, dependencies | `npx knip` |
37| `depcheck` | Unused npm dependencies | `npx depcheck` |
38| `ts-prune` | Unused TypeScript exports | `npx ts-prune` |
39| `vulture` | Unused Python code | `vulture src/` |
40| `deadcode` | Unused Go code | `deadcode ./...` |
41| `cargo-udeps` | Unused Rust dependencies | `cargo +nightly udeps` |
42
43If specialized tooling is unavailable, fall back to targeted search:
44
45- Find exported symbols and files.
46- Search for imports, requires, dynamic imports, route references, config references, and string-based lookups.
47- Treat "zero obvious references" as a lead, not proof.
48
49## Categorize Findings
50
51Assign every finding to a safety tier before editing.
52
53| Tier | Typical examples | Default action |
54| --- | --- | --- |
55| `SAFE` | Unused internal utilities, private helpers, unused tests/helpers, wrapper functions with no callers | Delete with verification |
56| `CAUTION` | Components, hooks, API routes, middleware, server actions, jobs, CLI commands | Investigate runtime and indirect usage first |
57| `DANGER` | Config files, entry points, exported types, schema files, generated boundaries, public APIs | Skip unless the user asks for deeper work |
58
59Escalate to a higher-risk tier when any of these are present:
60
61- Dynamic import paths
62- Reflection or registry lookups
63- String-based routing or command dispatch
64- Framework auto-discovery
65- Package public exports
66- External consumers or cross-repo usage
67
68## Safe Deletion Loop
69
70For each `SAFE` item:
71
721. Run the baseline verification.
732. Delete exactly one item with a surgical edit.
743. Re-run the relevant tests immediately.
754. If tests fail, restore the deletion and skip the item.
765. If tests pass, continue to the next item.
77
78Keep deletions atomic. Do not batch multiple unrelated removals into a single verification cycle.
79
80If a revert is needed:
81
82- Restore only the item under test.
83- Prefer non-destructive restore methods that do not disturb unrelated user changes.
84- Note the failure in the summary and move on.
85
86## Handle Caution Items
87
88Before deleting a `CAUTION` item, explicitly check for:
89
90- `import()` or `require()` usage
91- String references in configs, routes, registries, feature flags, and tests
92- Re-exports from package or app entry points
93- External consumers if the module is part of a published or shared surface
94- Framework conventions that auto-load files by name or location
95
96Delete a `CAUTION` item only when indirect usage has been ruled out and verification still passes.
97
98## Consolidate Duplicates
99
100After dead-code removals are green, look for low-risk consolidation:
101
102- Near-duplicate functions with the same behavior
103- Redundant type definitions
104- Pass-through wrappers that add no policy or ergonomics
105- Re-exports that add no discoverability or compatibility value
106
107Keep this phase separate from dead-code deletion. If consolidation changes behavior, stop treating it as cleanup and call it out explicitly.
108
109## Reporting
110
111End with a short cleanup report that includes:
112
113- Deleted functions, files, and dependencies
114- Skipped items and why
115- Approximate lines removed
116- Verification commands run
117- Final pass/fail state
118
119Use this format when it helps:
120
121```text
122Dead Code Cleanup
123----------------------------
124Deleted: 12 unused functions
125 3 unused files
126 5 unused dependencies
127Skipped: 2 items (verification failed)
128Saved: ~450 lines removed
129----------------------------
130All tests passing
131```
132
133## Rules
134
135- Never delete code before running a baseline verification step.
136- Remove one item at a time.
137- Skip uncertain findings instead of guessing.
138- Do not mix broad refactors into the deletion loop.
139- Preserve unrelated user changes while restoring failed deletions.
140- Be explicit about residual risk when `CAUTION` or `DANGER` items remain.