code-deletion-cleanup

Code Deletion Cleanup

This skill defines a conservative, principal-engineer workflow for deleting code while doing thorough cleanups. It is designed for everyday engineering tasks where deleting one target can create ripple effects across call graphs, modules, configuration, data, and tests.

Core Concepts

• Target: the function, class, module, file, feature flag, endpoint, job, or CLI command you intend to remove.
• Call site: any invocation or reference that reaches the target (imports, function calls, registrations, routing tables, reflection, string keys).
• Entry point: code that can be triggered externally or out of band (HTTP routes, CLI commands, scheduled jobs, message consumers, webhooks, public SDKs).
• Deletion queue: the ordered list of candidate items to delete next.

Hard Rules

• Only delete code when you can prove it is unused, or when the user explicitly accepts breaking changes.
• If you are uncertain, keep the code and report what you could not prove.
• Treat entry points and public contracts as high risk.
• Never delete entry points based on “no internal references” alone.
• Prefer repo-wide searches and build graph checks over file-local guesses.

Workflow

0) Preflight (Principal Engineer Step)

Before you delete anything, clarify the intent and constraints.

• Confirm the exact target(s) and the desired end state.
• Identify any entry points, public APIs, or documented behaviors involved.
• Confirm the breaking-change policy.
• Confirm data and retention implications (stored data, migrations, queued messages, file formats) if applicable.

If any of these are unclear, stop and ask questions.

1) Initialize a Deletion Queue

• Start with the user-provided deletion target.
• Add additional candidates only after verification.
• Use the task list tool (todowrite) as the canonical queue when the work spans multiple iterations.
• Model each queued item as a todo and advance statuses as you process items.
• When delegating repo-wide searches or inventories to subagents, create separate todos for each delegated chunk (for example "[explore] classify references for <symbol>").
• Use pending for not-yet-started items, in_progress for actively worked items, and completed once verified.
• It is acceptable to have multiple in_progress todos while subagents run in parallel, but keep ownership explicit in the todo text (for example prefix with [main] and [explore]).
• Keep the queue explicit in your narrative output.
• At the end of each iteration, print Queue now: ... (or equivalent from todoread).